Version 4.0.3

Transcription

Version 4.0.3

PDFlib GmbH München
Referenzhandbuch
®
Eine Bibliothek für dynamisches PDF
Version 4.0.3
ActiveX/COM- und .NET-Edition
www.pdflib.com
Copyright © 1997–2002 PDFlib GmbH und Thomas Merz. Alle Rechte vorbehalten.
PDFlib GmbH
Tal 40, 80331 München, Deutschland
http://www.pdflib.com
Tel. +49 • 89 • 29 16 46 87
Fax +49 • 89 • 29 16 46 86
Bei Fragen können Sie sich zunächst die PDFlib-Mailing-Liste und deren Archiv ansehen unter:
http://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 Dokumentation 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 Verwendbarkeit 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 Warenzeichen von Unicode, Inc. Unix ist ein Warenzeichen von The Open Group. Java und Solaris sind Warenzeichen
von Sun Microsystems, Inc. Die Namen von anderen Produkten und Diensten können Warenzeichen von
Unternehmen oder Organisationen sein, die hier nicht angeführt sind.
PDFlib enthält modifizierte Bestandteile folgender Software anderer Hersteller:
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.
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 Karsunke
Qualitätskontrolle (Manual): Petra Porst, York Karsunke
Qualitätskontrolle (Software): ein paar tausend Freiwillige
Inhaltsverzeichnis
1 Einführung
9
1.1 Programmierung mit PDFlib 9
1.2 Funktionalität von PDFlib 12
1.3 Ausgabe und Kompatibilität von PDFlib 12
2 Sprachbindungen von PDFlib
14
2.1 Übersicht 14
2.1.1 Was hat es mit all den Sprachbindungen auf sich? 14
2.1.2 Verfügbarkeit und Plattformen 14
2.1.3 Das Beispiel »Hello world« 14
2.1.4 Fehlerbehandlung 15
2.1.5 Versionskontrolle 15
2.1.6 Unicode-Unterstützung 16
2.1.7 Übersicht über die Sprachbindungen 16
2.2 ActiveX/COM-Sprachbindung 16
2.2.1 Arbeitsweise 16
2.2.2 Installation der ActiveX-Edition von PDFlib 17
2.2.3 Silent-Installation 18
2.2.4 Anwendungsszenarien 19
2.2.5 Fehlerbehandlung in ActiveX 20
2.2.6 Versionskontrolle in ActiveX 21
2.2.7 Unicode-Unterstützung in ActiveX 21
2.2.8 Einsatz von PDFlib mit Active Server Pages 22
2.2.9 Einsatz von PDFlib mit Visual Basic 26
2.2.10 Einsatz von PDFlib mit Windows Script Host 28
2.2.11 Einsatz von PDFlib mit ColdFusion 29
2.2.12 Einsatz von PDFlib mit Borland Delphi 30
2.3 C-Sprachbindung 32
2.4 C++-Sprachbindung 32
2.5 Java-Sprachbindung 32
2.6 .NET-Sprachbindung 32
2.6.1 Arbeitsweise 32
2.6.2 Installation von PDFlib.NET 32
2.6.3 Silent-Installation 33
2.6.4 Fehlerbehandlung in .NET 33
2.6.5 Versionskontrolle in .NET 33
2.6.6 Unicode-Unterstützung in .NET 33
2.6.7 Einsatz von PDFlib mit C# 34
2.6.8 Einsatz von PDFlib mit Visual Basic .NET 35
2.6.9 PDFlib ist nicht für ASP.NET freigegeben 37
Inhaltsverzeichnis
3
2.7 Perl-Sprachbindung 37
2.8 PHP-Sprachbindung 37
2.9 Python-Sprachbindung 37
2.10 RPG-Sprachbindung 37
2.11 Tcl-Sprachbindung 37
3 PDFlib- und PDI-Programmierung
38
3.1 Allgemeine Aspekte 38
3.1.1 Struktur eines PDFlib-Programms 38
3.1.2 Erzeugung von PDF-Dokumenten im Arbeitsspeicher 38
3.1.3 Fehlerbehandlung 39
3.2 Seitenbeschreibungen 40
3.2.1 Koordinatensysteme 40
3.2.2 Begrenzungen für Seiten und Koordinaten 42
3.2.3 Pfade und Farben 43
3.2.4 Templates 44
3.3 Textbehandlung 46
3.3.1 Die PDF-Standardschriften 46
3.3.2 In PDFlib integrierte 8-Bit-Zeichensätze 46
3.3.3 Benutzerdefinierte 8-Bit-Zeichensätze und Codepages 48
3.3.4 Das Eurozeichen 51
3.3.5 Zeichensätze für Hypertext 52
3.3.6 PostScript-, TrueType- und OpenType-Schriften 53
3.3.7 Ressourcekonfiguration und die UPR-Ressourcedatei 57
3.3.8 Japanischer, chinesischer und koreanischer Text 60
3.3.9 Unicode-Unterstützung 65
3.3.10 Textmetrik, Textvarianten und Formatierung in ein Rechteck 67
3.4 Verwendung von Rasterbildern 71
3.4.1 Unterstützte Rasterbildformate 71
3.4.2 Häufig benötigte Codefragmente für Rasterbilder 74
3.4.3 Wiederverwendung von Bilddaten 76
3.4.4 Bilddaten im Speicher und externe Bildreferenzen 76
3.4.5 Bildmasken und Transparenz 76
3.4.6 Einfärben von Bildern 79
3.4.7 Mehrseitige Bilddateien 80
3.5 PDF-Import mit PDI 80
3.5.1 PDI-Funktionen und -Anwendungen 80
3.5.2 Einsatz von PDI-Funktionen mit PDFlib 81
3.5.3 Importierbare PDF-Dokumente 83
3.5.4 PDF-Import, Templates und Vererbung des Grafik- und Textzustands 84
4
Inhaltsverzeichnis
4 PDFlib- und PDI-API-Referenz
85
4.1 Datentypen, Namenskonventionen und Geltungsbereiche 85
4.2 Allgemeine Funktionen 86
4.2.1 Setup 86
4.2.2 Dokument und Seite 87
4.2.3 Parameterbehandlung 89
4.3 Textfunktionen 90
4.3.1 Fontbehandlung 90
4.3.2 Textausgabe 92
4.4 Grafikfunktionen 96
4.4.1 Funktionen für den Grafikzustand 96
4.4.2 Speichern und Wiederherstellen des Grafikzustands 99
4.4.3 Funktionen zur Transformation des Koordinatensystems 100
4.4.4 Pfadkonstruktion 102
4.4.5 Zeichnen und Beschneiden von Pfaden 104
4.5 Farbfunktionen 106
4.6 Rasterbildfunktionen 109
4.7 Funktionen zum PDF-Import (PDI) 114
4.7.1 Dokument und Seite 114
4.7.2 Parameterbehandlung 116
4.8 Hypertextfunktionen 118
4.8.1 Aktion und Modus beim Öffnen des Dokuments 118
4.8.2 Lesezeichen 118
4.8.3 Dokumentinfofelder 120
4.8.4 Seitenübergänge 120
4.8.5 Dateianlagen 121
4.8.6 Notizen 122
4.8.7 Verknüpfungen (Links) 122
4.8.8 Piktogramme (Thumbnails) 125
4.9 Seitenformate 126
5 Die PDFlib-Lizenz
127
5.1 Die »Aladdin Free Public License« 127
5.2 Die kommerzielle PDFlib-Lizenz 127
6 Literaturhinweise
128
A Dynamische Bibliotheken (DLLs)
B PDFlib-Kurzreferenz
129
130
C Änderungen an diesem Handbuch
134
Inhaltsverzeichnis
5
Index
6
135
Inhaltsverzeichnis
0 Anwendung des PDFlibLizenzschlüssels
Alle Binärversionen von PDFlib und PDI, die Sie von PDFlib GmbH beziehen, sind als
Entwicklungsversionen in vollem Funktionsumfang verwendbar, unabhängig davon,
ob Sie eine kommerzielle Lizenz erworben haben oder nicht. Bei nicht lizenzierten Versionen wird jedoch quer über allen generierten Seiten der Demostempel www.pdflib.com
ausgegeben. Unternehmen, die an einer Lizenzierung von PDFlib interessiert sind und
den Demostempel in der Evaluierungsphase oder ersten Demos vermeiden möchten,
können ihre Firmen- und Projektdaten an [email protected] senden und einen temporären Lizenzschlüssel anfordern.
Nachdem Sie einen Lizenzschlüssel für PDFlib oder PDI erworben haben, müssen Sie
ihn erst noch anwenden, damit der Demostempel auch tatsächlich unterdrückt wird.
Dazu gibt es mehrere Möglichkeiten:
> Fügen Sie in Ihrem Skript oder Programm eine Zeile ein, die die Seriennummer zur
Laufzeit setzt:
oPDF.set_parameter("serial", "...Ihre Seriennummer...")
Die Seriennummer darf nur einmal gesetzt werden, und dies muss unmittelbar nach
der Instantiierung des PDFlib-Objekts erfolgen .
> Setzen Sie eine Umgebungsvariable (Shellvariable), bevor Sie PDFlib-Funktionen aufrufen. Wie Sie dazu genau vorgehen, hängt vom jeweiligen System an. Der Befehl in
einer Unix-Shell könnte zum Beispiel wie folgt aussehen:
export PDFLIBSERIAL="...Ihre Seriennummer..."
> Benutzer der ActiveX/COM- oder .NET-Edition können die Seriennummer auch übergeben, wenn sie PDFlib/PDI mit der mitgelieferten Installationsroutine installieren.
In diesem Fall ist der obige Funktionsaufruf überflüssig (siehe auch Abschnitt 2.2.2,
»Installation der ActiveX-Edition von PDFlib«, Seite 17).
Beachten Sie, dass PDFlib und PDI unterschiedliche Produkte sind, die unterschiedliche
Seriennummern benötigen, obwohl sie in demselben Paket ausgeliefert werden. PDI-Seriennummern gelten zwar auch für PDFlib, aber nicht umgekehrt. Außerdem sind die
Seriennummern für PDFlib und PDI plattformabhängig und können somit nur auf der
Plattform verwendet werden, für die sie erworben wurden.
7
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 Programme. Sie als Programmierer sind verantwortlich für die Verwaltung der zu verarbeitenden Daten, und PDFlib übernimmt die Generierung des PDF-Codes, der die Daten
grafisch darstellt. Die Formatierung und Anordnung der Text- und Grafikobjekte bleibt
zwar Ihre Aufgabe, Sie brauchen sich aber nicht um einzelne Details des komplexen
PDF-Formats zu kümmern. PDFlib bietet zahlreiche nützliche Funktionen zur Erstellung
von Text, Vektorgrafik, Rasterbildern und Hypertextelementen in PDF.
Wie wird PDFlib eingesetzt? PDFlib ist auf verschiedensten Plattformen einsetzbar,
unter anderem auf Unix, Windows, Mac OS und EBCDIC-basierten Systemen wie IBM
eServer iSeries 400 und zSeries S/390. PDFlib ist in der Programmiersprache C geschrie-
Abb. 1.1 Das Innenleben von PDFlib
PHP
Tcl
Perl
)
c(
ar
F_
PD
t( )
etfon
PDF_s
()
eto
_lin
F
D
P
PD
F_s
ho
w(
)
(
cle
cir
_
F
PD
Python
)
Java
C
C++
Activ
eX
9
ben, unterstützt aber den Zugriff von diversen anderen Programmersprachen und Programmierumgebungen, die Sprachbindungen genannt werden und alle verbreiteten
Sprachen für Webanwendungen umfassen. Das Application Programming Interface (API)
ist einfach zu erlernen und für alle Sprachbindungen gleich. Derzeit werden folgende
Sprachbindungen unterstützt:
> ActiveX/COM für den Einsatz mit Visual Basic, Active Server Pages mit VBScript oder
JScript, Allaire ColdFusion, Borland Delphi, Windows Script Host und anderen Umgebungen
> ANSI C
> ANSI C++
> Java inklusive Servlets
> .NET für den Einsatz mit C#, VB.NET und anderen Umgebungen
> PHP
> Perl
> Python
> RPG (IBM eServer iSeries 400)
> Tcl
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 Webserver 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
Webservers abgerufen werden. Die Arbeitsweise und Struktur 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 – PostScript – Acrobat Distiller – PDF« überflüssig.
> Aufgrund dieser Vereinfachung bietet PDFlib die schnellstmögliche Methode zur Generierung von PDF, die sich ideal für den Einsatz im Web eignet.
> Durch Thread-Sicherheit, stabile Speicherverwaltung und Fehlerbehandlung wird
die Implementierung von Server-Anwendungen mit höchsten Performance-Anforderungen unterstützt.
> PDFlib ist für eine Vielzahl von Betriebssystemen und Entwicklungsumgebungen
verfügbar.
PDFlib kann jedoch nicht nur zur dynamischen Erzeugung von PDF im Web eingesetzt
werden. Genauso wichtig sind Konverter von X nach PDF, wobei X für ein beliebiges
Text- oder Grafikdateiformat steht. Auch in diesem Fall verkürzt sich der Weg von »X–
PostScript–PDF« zu »X–PDF«. Dies bringt zahlreiche Vorteile für gängige Grafikdateiformate wie zum Beispiel TIFF, GIF, PNG und JPEG. Mithilfe eines solchen PDF-Konverters
lassen sich große Mengen von Text- oder Grafikdateien im Batch-Verfahren viel einfacher konvertieren als mit Adobe Acrobat.
Anforderungen an den Einsatz von PDFlib. Mit PDFlib können Sie PDF generieren,
ohne sich vorher durch die mehr als 900 Seiten starke PDF-Spezifikation zu quälen. Der
Einsatz von PDFlib setzt zwar kein Wissen über die technischen Einzelheiten des PDFFormats voraus, ein allgemeines 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
10
Kapitel 1: Einführung (ActiveX/COM- und .NET-Edition)
Tabelle 1.1 PDFlib-Funktionalität zur PDF-Generierung
Kategorie
Funktionalität
PDF-Import
> vorhandene PDF-Dokumente können mit der optionalen PDF-Import-Bibliothek (PDI) importiert werden
PDF-Ausgabe > PDF-Dokumente beliebiger Länge, direkt im Arbeitsspeicher (für Webserver) oder auf Festplatte
Vektorgrafik
Schriften
> beliebige Anzahl von Seiten und beliebige Seitenformate
> Kompression von Text, Vektorgrafik, Rasterbilddaten und Dateianlagen
> Kompatibilitätsmodus für PDF 1.2, 1.3 und 1.4 (Acrobat 3, 4 und 5)
> übliche Basisfunktionen für Vektorgrafik: Linienzüge, Kurvenzüge, Kreise, Rechtecke etc.
> Vektorpfade zum Zeichnen, Füllen und Beschneiden
> Graustufen, RGB, CMYK und Schmuckfarbe zum Zeichnen und Füllen von Objekten
> Füllen von Flächen und Durchziehen von Linien mit Mustern
> effiziente Wiederverwendung von Text oder Vektorgrafik durch Templates
> Textausgabe in verschiedenen Schriften; unterstrichener, überstrichener, durchgestrichener Text
> Formatieren von Text
> Unterstützung der Schriftformate TrueType, PostScript Type 1 (Dateiformate PFB und PFA, plus
LWFN auf dem Mac) und OpenType mit oder ohne Schrifteinbettung; Auf Windows und Mac
können im System installierte TrueType-Schriften genutzt werden.
Hypertext
> Unterstützung von AFM- und PFM-Metrikdateien für PostScript-Fonts
> Bibliotheksclients können Zeichenmetrik zur exakten Formatierung abrufen
> auf IBM eServer iSeries 400 und zSeries S/390: Abfragen von Encodings vom Betriebssystem
> Seitenübergänge in der Vollbildanzeige
> Verschachtelte Lesezeichen
> PDF-Verknüpfungen, Links auf andere Dokumenttypen und Weblinks
> Dokumentinformation: vier Standardfelder (Titel, Thema, Autor, Stichwörter) plus unbegrenzte
Anzahl von benutzerdefinierten Infofeldern (zum Beispiel Artikelnummer)
Internationalisierung
Unicode
> Dateianlagen und Notizen
> Unicode-Unterstützung (siehe unten)
> Unterstützung verschiedenster Encodings (sowohl integriert als auch benutzerdefiniert)
> Unterstützung von CID-Schriften und CMaps für chinesisch, japanisch und koreanisch
> Unterstützung des Eurozeichens
> Unterstützung internationaler Standards und herstellerspezifischer Codepages
> Unicode-Unterstützung für Hypertextfunktionen: Lesezeichen, Inhalt und Titel von Notizen,
Dokumentinfofelder, Beschreibung und Autor von Dateianlagen
Rasterbilder
Programmierung
> Unicode-Codepages für TrueType- und PostScript-Schriften
> Unicode-Encoding für japanischen, chinesischen und koreanischen Text
> Einbettung von Rasterbildern in den Formaten GIF (nicht-interlaced), PNG, TIFF, JPEG und CCITT
> Rasterbilder, die vom Client direkt im Speicher erzeugt werden
> Effiziente Wiederverwendung der Bilddaten, zum Beispiel für Logos auf jeder Seite
> transparente (maskierte) Bilder und Bildmasken (eingefärbte Bilder)
> Einfärben von Bildern mit Schmuckfarbe
> Sprachbindungen für ActiveX/COM, C, C++, Java (inkl, Servlets), .NET, Perl, PHP, Python, RPG, Tcl
> transparente Unicode-Behandlung für ActiveX, Java und Tcl
> Thread-Sicherheit zum Einsatz in »multi-threaded« Serveranwendungen
> Error-Handler und Speicherverwaltung konfigurierbar für C und C++
> Ausnahmebehandlung integriert in die Ausnahmebehandlung der Zielsprache
> verfügbar für verschiedenste Systeme, einschließlich ASCII- und EBCDIC-basierter Plattformen
11
auch ein Anwendungsprogrammierer, der bereits mit einem Grafik-API für Bildschirmanzeige oder Ausdruck gearbeitet 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. In
diesem Handbuch werden keine Acrobat-Funktionen erklärt. Diesbezügliche Informationen finden Sie in der Literatur zu Acrobat und in den Literaturhinweisen am Ende dieses Handbuchs.
1.2 Funktionalität von PDFlib
Tabelle 1.1 zeigt eine Liste der wichtigsten PDFlib-Funktionen zum Erstellen von PDFDokumenten.
1.3 Ausgabe und Kompatibilität von PDFlib
PDFlib-Ausgabe. Die von PDFlib generierte binäre PDF-Ausgabe ist mit dem FlateAlgorithmus (auch als ZIP bekannt) komprimiert, wobei sich die Kompression wahlweise deaktivieren lässt. Komprimiert werden Elemente, die sehr groß werden können, wie
zum Beispiel Dateianlagen oder Rasterbilder (sofern sie nicht bereits vorkomprimiert
sind, wie es etwa bei JPEG der Fall ist), außerdem Text- und Vektoroperatoren auf Seitenbeschreibungen. Die Abwägung zwischen Kompressionsgeschwindigkeit und Ausgabegröße lässt sich über einen PDFlib-Parameter steuern.
Funktionalität von Acrobat 4. Wir sind generell darum bemüht, PDF-Dokumente zu
erstellen, die von einem breiten Spektrum von PDF-Viewern verwendbar sind. Die von
PDFlib generierte Ausgabe ist zu Acrobat 3 oder höher kompatibel.
Manche Merkmale erfordern jedoch Acrobat 4 oder funktionieren nur in der Acrobat-Vollversion und nicht in Acrobat Reader. Eine Übersicht dazu zeigt Tabelle 1.2. Weitere Informationen hierzu finden Sie in der jeweiligen Funktionsbeschreibung.
Tabelle 1.2 PDFlib-Funktionen, die Acrobat 4 oder höher benötigen
Kategorie
Bemerkungen
Hypertext
> Dateianlagen werden in Acrobat 3 nicht erkannt (Acrobat-4-Vollversion erforderlich)
> verschiedene Symbole für Notizen werden in Acrobat 3 nicht erkannt
> in Acrobat 4 wurde die maximale Seitengröße in PDF-Dateien erhöht
> keine Unterstützung von Unicode-Hypertext in Acrobat 3
> keine Unterstützung des Eurozeichens in Acrobat 3
> keine Unicode-Unterstützung für TrueType-Schriften in Acrobat 3
> CID-Schriften für Chinesisch, Japanisch und Koreanisch benötigen Acrobat 3J oder Acrobat 4
> Der »Pattern«-Farbraum wird im Kompatibilitätsmodus für Acrobat 3 nicht unterstützt (Füll-
Seitengröße
Unicode
Schriften
Farbe
muster werden mit Acrobat 3 zwar gedruckt, aber nicht am Bildschirm angezeigt)
Transparenz
JPEG-Bilder
externe
Bilder
12
> Informationen bezüglich Transparenz werden in Acrobat 3 ignoriert
> Acrobat 3 unterstützt nur Bilder mit Baseline- und nicht solche mit Progressive-Kompression
> Acrobat 4 (aber nicht der kostenlose Acrobat Reader) unterstützt Referenzen auf externe Rasterbilder über einen URL. Acrobat 3 kann auf diese Art referenzierte Bilder nicht anzeigen.
Kapitel 1: Einführung (ActiveX/COM- und .NET-Edition)
Kompatibilitätsmodus für Acrobat 3. Wenn Sie keine spezielle Acrobat-4-Funktionalität einsetzen, sind die erzeugten PDF-Dateien im Prinzip zu Acrobat 3 und 4 kompatibel.
Aufgrund eines seltenen Kompatibilitätsproblems bei bestimmten Ausgabegeräten
bietet PDFlib aber auch einen strengen Kompatibilitätsmodus für Acrobat 3. Um das
Problem zu verstehen, muss man zwischen der tatsächlich für eine bestimmte PDFDatei erforderlichen Acrobat-Viewerversion und der allerersten Zeile in der Datei unterscheiden, die %PDF-1.2 bei zu Acrobat 3 kompatiblen Dateien und %PDF-1.3 bei zu Acrobat
4 kompatiblen Dateien lautet. Acrobat-3-Viewer können Dateien, die mit der Zeile %PDF1.3 beginnen, problemlos öffnen, sofern diese keine Acrobat-4-Funktionalität enthält.
Auf diesem Verhalten basiert das Verfahren von PDFlib zur Kompatibilität verschiedener Versionen.
Im Gegensatz zu Acrobat gibt es jedoch auch PDF-Viewer, die eine wesentlich strengere Art der Versionssteuerung implementieren: Sie weisen einfach alle Dateien ab, die
mit der Zeile %PDF-1.3 beginnen, unabhängig davon, ob der eigentliche Inhalt einen Interpreter für PDF 1.2 oder für PDF 1.3 benötigt. Von einigen EfI-RIPs für digitale Druckmaschinen ist zum Beispiel bekannt, dass sie sich in dieser Art (fehl-)verhalten. Um das
Problem zu umgehen, bietet PDFlib einen strikten Kompatibilitätsmodus für Acrobat 3,
in welchem eine Anfangszeile mit %PDF-1.2 ausgegeben und alle Acrobat-4-Funktionen
deaktiviert werden.
Um es noch einmal zu betonen: Der in PDFlib verfügbare strikte Kompatibilitätsmodus für Acrobat 3 ist nicht erforderlich, um sicherzustellen, dass PDF-Dateien in Acrobat
3 geöffnet werden können – dies ist automatisch der Fall, wenn Sie keine der oben erwähnten Acrobat-4-Funktionen verwenden. Der strenge Modus ist nur sehr selten erforderlich, und zwar genau dann, wenn Sie mit einem dieser sich so merkwürdig verhaltenden PDF-fähigen RIPs zu tun haben.
Kompatibilität zu Acrobat 5. PDFlib akzeptiert zu Acrobat 5 kompatible PDF-Dateien
beim Import und wird in zukünftigen Versionen auch Acrobat-5-Funktionalität generieren. Die Ausgabe-Kompatibilität kann auf PDF 1.4 (=Acrobat 5) eingestellt werden,
wenn zu Acrobat 5 kompatible PDF-Dateien in das generierte Dokument importiert werden sollen. Die PDF-Importbibliothek PDI bietet vollständige Unterstützung von PDF 1.4
(siehe Abschnitt 3.5.2, »Einsatz von PDI-Funktionen mit PDFlib«, Seite 81).
1.3 Ausgabe und Kompatibilität von PDFlib
13
2 Sprachbindungen von PDFlib
2.1 Übersicht
2.1.1 Was hat es mit all den Sprachbindungen auf sich?
Die Programmiersprache C war jahrzehntelang maßgebliches Werkzeug bei der Entwicklung von System- und Anwendungssoftware. Seit geraumer Zeit gibt es eine ganze
Reihe anderer Sprachen, die sich entweder auf neue Programmierparadigmen stützen
(zum Beispiel C++), den Weg zu leistungsfähigen und plattformunabhängigen Skripten
bereiten (zum Beispiel Perl, Tcl oder Python), eine neue Qualität in der Portierbarkeit
versprechen (zum Beispiel Java) oder eine Verbindung zwischen unterschiedlichsten
Techniken schaffen und dabei plattformabhängig sind (zum Beispiel ActiveX/COM).
Hinweis Die vorliegende Handbuchausgabe befasst sich nur mit der ActiveX/COM- und .NET-Edition
von PDFlib. Alle anderen Sprachbindungen werden ausführlich in einer anderen Ausgabe des
Handbuchs erläutert. Abschnitte, die für Benutzer der ActiveX/COM-Edition von PDFlib nicht
relevant sind, wurden in dieser Ausgabe weggelassen.
2.1.2 Verfügbarkeit und Plattformen
Die Funktionalität von PDFlib ist auf allen Plattformen und in allen Sprachbindungen
identisch (mit ein paar kleineren Ausnahmen, auf die im Handbuch hingewiesen wird).
In Anbetracht des von PDFlib unterstützten immensen Spektrums an Plattformen und
Sprachen (und zahlreichen verschiedenen Versionen) dürfte es nicht überraschen, dass
nicht alle Kombinationen von Plattformen, Sprachen und Versionen getestet werden
konnten. Wir sind aber nach Kräften bemüht, PDFlib mit den neuesten Versionen der jeweiligen Umgebungen lauffähig zu machen. Tabelle 2.1 zeigt die Kombinationen aus
Sprache und Plattform, die wir für unsere Tests verwendet haben.
PDFlib auf Embedded-Systemen. PDFlib kann auch auf Embedded-Systemen eingesetzt werden. Die Bibliothek wurde auf die Umgebungen Windows CE 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.1.3 Das Beispiel »Hello world«
Für unsere Programmierbeispiele haben wir uns für den Klassiker »Hello, world!« entschieden. Er nutzt PDFlib zur Erzeugung einer einseitigen PDF-Datei mit etwas Text auf
der Seite. In den folgenden Abschnitten wird das Beispiel »Hello world« für alle unterstützten Sprachbindungen vorgeführt. Der Code für alle Sprachbeispiele ist in der
PDFlib-Distribution enthalten. Die Distribution umfasst einfache Beispiele für die Behandlung von Text, Vektorgrafik und Rasterbildern sowie den PDF-Import für alle unterstützten Sprachbindungen.
14
Kapitel 2: Sprachbindungen von PDFlib (ActiveX/COM- und .NET-Edition)
Tabelle 2.1 Getestete Kombinationen von Sprachen und Plattformen
Windows
Mac OS (Classic)
IBM eServer iSeries
400, zSeries S/390
ActiveX/COM –
ASP (PWS, IIS 4 und 5)
WSH (VBScript 5, JScript 5)
Visual Basic 6.0
Borland Delphi 5 und 6
ColdFusion 4.5
–
–
ANSI C
gcc
und andere ANSI-CCompiler
Microsoft Visual C++ 6.0
Metrowerks CodeWarrior 6, 7
Borland C++ Builder 5
Metrowerks
CodeWarrior 6, 7
IBM c89
SAS C für MVS
ANSI C++
gcc und andere ANSI- Microsoft Visual C++ 6.0
C++-Compiler
Metrowerks CodeWarrior 6, 7
Metrowerks
CodeWarrior 6, 7
IBM c89
Java
Sun JDK 1.2.2 und 1.3
IBM JDK 1.1.8
Inprise JBuilder 3.5
Kaffe OpenVM 1.0.5
Sun JDK 1.1.8, 1.2.2 und 1.3
Inprise JBuilder 3.5 und 4
JRun 3.0
ColdFusion 4.5
MRJ 2.2,
basiert auf JDK 1.1.8
JDK 1.2, 1.3
.NET
–
.NET Framework 1.0
–
–
Perl
Perl 5.005, 5.6
ActivePerl 5.005 und 5.6
MacPerl 5.2.0r4
und 5.6.1a5
–
Sprache
Unix (Linux, Solaris,
HP-UX, AIX u.a.)
PHP
PHP 4.04 - 4.2.1
PHP 4.04 - 4.2.1
–
–
Python
Python 1.6, 2.0 - 2.2
Python 1.6, 2.0 - 2.2
Python 2.0 und 2.1.1
–
RPG
–
–
–
V3R7M0 und höher
Tcl
Tcl 8.3.2 und 8.4a2
Tcl 8.3.2 und 8.4a2
Tcl 8.3.2
–
2.1.4 Fehlerbehandlung
PDFlib bietet ausgefeilte Mechanismen zum Umgang mit verschiedenartigen Programmier- und Laufzeitfehlern. Um eine nahtlose Integration in die jeweilige Sprachumgebung zu gewährleisten, wird die Fehlerbehandlung von PDFlib in die der jeweiligen
Sprache eigenen Ausnahmebehandlung integriert. C- und C++-Clients können benutzerdefinierten Code installieren, der im Fehlerfall aufgerufen wird. Andere Sprachbindungen arbeiten mit den Ausnahmemechanismen, die in allen modernen Sprachen
vorhanden sind. Weitere Informationen über die Ausnahmebehandlung von PDFlib finden Sie in Abschnitt 3.1.3, »Fehlerbehandlung«, Seite 39. Die Abschnitte, die sich in diesem Kapitel mit der Fehlerbehandlung befassen, behandeln sprachspezifische Details
der unterstützten Umgebungen.
2.1.5 Versionskontrolle
In Anbetracht der kurzen Entwicklungszyklen von Software im allgemeinen und Internet-Software im besonderen ist es wichtig, zukünftige Verbesserungen so einzuplanen,
dass vorhandene Clients davon nicht beeinträchtigt werden. Um Kompatibilität zwischen verschiedenen Versionen der Bibliothek zu gewährleisten, unterstützt PDFlib
mehrere Mechanismen zur Versionskontrolle, die von der jeweiligen Sprache abhängen. Wenn die Sprache selbst einen Versionierungsmechanismus unterstützt, so wird
dieser von PDFlib nahtlos integriert. Der Client braucht sich dann nicht um Versionierung zu kümmern, sondern verwendet einfach die von der Sprache gebotenen Mechanismen. Wenn die Sprache selbst keine geeigneten Versionierungsmöglichkeiten bietet,
liefert PDFlib auf Schnittstellenebene eigene Major-, Minor- und Revision-Versionsnum-
2.1 Übersicht
15
mern. Anhand dieser Nummern kann der Client entscheiden, ob die jeweilige PDFlibImplementierung verwendet werden kann oder abgelehnt werden muss, weil eine neuere Version erforderlich ist.
2.1.6 Unicode-Unterstützung
PDFlib bietet Unicode-Unterstützung für zahlreiche Funktionen (Einzelheiten hierzu
finden Sie in Abschnitt 3.3.9, »Unicode-Unterstützung«, Seite 65). Die Sprachbindungen
weisen allerdings Unterschiede in der nativen Unicode-Unterstützung auf. Unterstützt
eine Sprachbindung Unicode-Strings, so erkennt der zugehörende PDFlib-Sprachwrapper dies und verarbeitet die Unicode-Strings automatisch auf korrekte Art und Weise.
2.1.7 Übersicht über die Sprachbindungen
Zum schnellen Nachschlagen zeigt Tabelle 2.2 eine Übersicht über die wesentlichen Eigenschaften der verschiedenen PDFlib-Sprachbindungen. Weitere Informationen finden Sie in den jeweiligen Handbuchabschnitten.
Tabelle 2.2 Übersicht über die Eigenschaften der verschiedenen Sprachbindungen
UnicodeKonvertierung Versionskontrolle
EBCDICthread-sicher sicher
COM/ActiveX COM-Exceptions
ja
Class ID und ProgID
ja (boththreading)
–
C
vom Client
gelieferter ErrorHandler
–
manuell
ja
ja
Sprache
benutzerdefinierte
Fehlerbehandlung
C++
C++-Exceptions
–
manuell
ja
ja
Java
Java-Exceptions
ja
automatisch
ja
ja
NET
.NET-Exceptions
ja
Major/Minor/
Revision
ja
–
Perl
Perl-Exceptions
–
über PackageMechanismus
–
–
PHP
PHP-Warnungen
–
manuell
ja
–
Python
Python-Exceptions
–
manuell
–
–
RPG
RPG-Exceptions
–
manuell
–
ja
Tcl
Tcl-Exceptions
ja (Tcl 8.2
und höher)
über PackageMechanismus
ja
–
2.2 ActiveX/COM-Sprachbindung
2.2.1 Arbeitsweise
COM (Component Object Model)1, das von Microsoft entwickelt wurde, ist ein leistungsfähiges Verfahren zur Wiederverwendung von Software-Komponenten. Dabei spielt es
keine Rolle, welche Programmiersprache auf der Client-Seite (dem Benutzer der Komponente) oder auf der Server-Seite (der Komponente selbst) eingesetzt wird. Theoretisch
1. Weitere Informationen zu COM und ActiveX finden Sie unter http://www.microsoft.com/com.
16
ist COM ein plattformunabhängiger Binärstandard, über den Clients mit Servern im selben Prozess auf demselben Rechner oder auf einem anderen Rechner im Netz kommunizieren können. In der Praxis jedoch ist COM ein Standard für Windows .
ActiveX baut auf der COM-Technik von Microsoft auf. Es wird in erster Linie zur Entwicklung interaktiver Inhalte für das World Wide Web verwendet, kann aber auch in
Desktop- und anderen Anwendungen eingesetzt werden. Die wiederverwendbaren Software-Komponenten werden ActiveX-Controls genannt (früher OLE-Controls oder OCX).
ActiveX belastet den Entwickler zwar mit einer Vielzahl sehr spezieller Techniken, Bezeichnungen und Konzepten (wie zum Beispiel Type-Libraries, Registrierung, verschiedene Threading-Modelle, historischer Ballast etc.), ActiveX-Benutzer werden dafür aber
mit nahtloser Integration und fast universeller Verwendbarkeit belohnt (sofern sie sich
im Windows-Universum bewegen).
Da PDFlib eine reine Entwicklungskomponente ist, eignet sie sich von Natur aus zur
ActiveX-Implementierung für den Einsatz unter Windows. Die ActiveX-Implementierung von PDFlib ist als Wrapper-DLL um den PDFlib-Kern gelegt. Die Wrapper-DLL ruft
die PDFlib-Kernfunktionen auf und ist verantwortlich für die Kommunikation mit den
zugrunde liegenden COM-Mechanismen, Registrierung und Type-Library, COM-Ausnahmebehandlung, Speicherverwaltung und Konvertierung von Unicode-Strings. Die
technischen Daten des ActiveX-Wrappers von PDFlib lauten wie folgt (zerbrechen Sie
sich nicht den Kopf, wenn Ihnen nicht alle Aspekte geläufig sind – diesbezügliche
Kenntnisse sind für den Einsatz von PDFlib nicht erforderlich):
> PDFlib fungiert als Win32 in-process ActiveX-Serverkomponente (auch Automation
Server genannt) ohne Benutzeroberfläche.
> PDFlib ist eine both-threaded Komponente, das heißt, sie wird sowohl als apartmentthreaded als auch als free-threaded Komponente behandelt. Außerdem nutzt PDFlib
einen free-threaded marshaller. Clients können das PDFlib-Objekt also direkt verwenden (statt eine Proxy/Stub-Kombination nutzen), was eine erhebliche PerformanceSteigerung zur Folge hat.
> PDFlib ist voll Unicode-fähig.
> Die PDFlib-Binärdatei pdflib_com.dll ist eine selbstregistrierende DLL mit einer TypeLibrary.
> PDFlib ist zustandslos, das heißt statt Properties werden Methoden-Parameter verwendet.
> Die duale Schnittstelle von PDFlib unterstützt sowohl frühe als auch späte Bindung.
> PDFlib unterstützt ausführliche Fehlerinformationen.
Hinweis PDFlib ist gegenwärtig zwar nicht MTS-fähig (Microsoft Transaction Server), kann aber mit MTS
eingesetzt werden.
2.2.2 Installation der ActiveX-Edition von PDFlib
PDFlib kann in allen Umgebungen eingesetzt werden, die ActiveX-Komponenten unterstützen. Wir zeigen unsere Beispiele in den folgenden Umgebungen:
> Visual Basic
> Active Server Pages (ASP) mit JScript und VBScript
> Windows Script Host (WSH) mit JScript und VBScript
> Allaire ColdFusion
> Borland Delphi
17
Active Server Pages und Windows Script Host unterstützen JScript und VBScript. Da die
Skripten fast identisch sind, werden wir hier nicht alle Kombinationen vorführen. Außerdem gibt es noch viele andere ActiveX-fähige Entwicklungsumgebungen – unter anderem Microsoft Visual C++, Borland C++ Builder oder PowerBuilder. PDFlib funktioniert auch in Visual Basic for Applications (VBA).
Voraussetzungen für die PDFlib-Installation. Die Installation von PDFlib ist einfach zu
bewerkstelligen. Beachten Sie dabei Folgendes:
> PDFlib läuft unter allen Versionen von Windows. Es ist keine bestimmte Betriebssystemversion und kein bestimmtes Service Pack erforderlich.
> Wenn Sie PDFlib auf einer NTFS-Partition installieren, brauchen alle PDFlib-Benutzer
die Lesen-Berechtigung auf das Installationsverzeichnis und die Ausführen-Berechtigung für ...\PDFlib\bin\pdflib_com.dll.
> Der installierende Benutzer benötigt die Schreiben-Berechtigung für die Registrierungsdatenbank. Administrator-Berechtigungen oder Berechtigungen der Gruppe
»Hauptbenutzer« reichen in der Regel aus.
Die .exe- und MSI-Installationsroutinen von PDFlib. PDFlib wird mit einer konventionellen .exe-Installationsroutine ausgeliefert, die alle erforderlichen Installationsschritte
durchführt. Alternativ dazu ist PDFlib als MSI-Paket verfügbar (Microsoft Windows Installer), der über zusätzliche Installations-, Reparatur- und Deinstallationsfunktionen
verfügt. Auf Systemen, die mit Windows Installer ausgestattet sind (zum Beispiel Windows 2000 und XP) besitzt die MSI-Installation der PDFlib einige Vorteile gegenüber der
.exe-Installation. Um PDFlib mit dem MSI-Paket zu installieren, doppelklicken Sie einfach auf die .msi-Datei oder klicken sie mit der rechten Maustaste an und wählen
Installieren.
Was passiert bei der ActiveX-Installation von PDFlib? Die Installationsroutinen, die
mit der ActiveX-Komponente von PDFlib ausgeliefert werden, regeln automatisch alle
Aspekte, die für den PDFlib-Einsatz mit ActiveX relevant sind. Der Vollständigkeit halber beschreiben wir trotzdem im Folgenden, welche Laufzeitumgebung für den PDFlibEinsatz erforderlich ist (die von der Installationsroutine automatisch so eingestellt
wird):
> Die PDFlib ActiveX-DLL pdflib_com.dll wird ins Installationsverzeichnis kopiert.
> Die PDFlib ActiveX-DLL muss in der Windows-Registrierung eingetragen sein. Um
eine Registrierung zu erreichen, verwendet die Installationsroutine die selbstregistrierende PDFlib-DLL.
> Wird eine lizenzierte Version von PDFlib installiert, dann wird die Seriennummer ins
System eingetragen.
Die Installationsoption Runtime führt die oben genannten Schritte durch. Die Installationsoption Full kopiert zusätzlich Dokumentation und Beispieldateien ins Installationsverzeichnis.
2.2.3 Silent-Installation
Wird PDFlib als Bestandteil eines anderen Software-Pakets ausgeliefert oder auf sehr
vielen Rechnern eingesetzt, die mit einem Tool wie SMS verwaltet werden, ist es äußerst
mühsam, PDFlib auf jedem Rechner einzeln manuell zu installieren. Für solche Situatio-
18
nen gibt es die Möglichkeit, PDFlib automatisch ohne jede Benutzerinteraktion zu installieren.
Silent-Installation mit der .exe-Installationsroutine. Die .exe-Installationsroutine von
PDFlib wurde mit InstallShield erstellt und unterstützt auch dessen Silent-Installation.
Eine normale (nicht-silent) Installation bezieht ihren Input aus Dialogfeldern, in die der
Benutzer alle erforderlichen Informationen eingibt. Eine Silent-Installation arbeitet dagegen nicht mit Dialogfeldern, sondern bezieht die Informationen aus einer besonderen Datei des Typs InstallShield Silent Response (.iss). Dabei handelt es sich um eine Textdatei, die in etwa diejenigen Informationen enthält, die ein Benutzer beim normalen
Setup in Dialogfelder eingeben würde. Die Response-Datei lässt sich am einfachsten
vorbereiten, indem eine interaktive Installation durchgeführt und dabei alle Benutzereingaben aufgezeichnet werden.
Um eine (nicht-interaktive) Silent-Installation von PDFlib durchzuführen, gehen Sie
wie folgt vor:
> Extrahieren Sie die PDFlib-ActiveX-Installationsdateien mit WinZip in das gewünschte Verzeichnis.
> Führen Sie in diesem Verzeichnis setup -r aus und geben Sie in den Dialogfeldern genau die Informationen ein, die später in der Silent-Installation verwendet werden
sollen.
> Kopieren Sie die Response-Datei setup.iss, die in Ihrem Windows-Verzeichnis abgelegt wurde, in das Verzeichnis mit den Installationsdateien. Bei Bedarf können Sie
die Angaben in der Response-Datei mit einem Texteditor nachträglich verändern.
> Starten Sie die Silent-Installation, indem Sie setup -s im Verzeichnis mit den Installationsdateien ausführen.
Silent-Installation mit der MSI-Installationsroutine. Auch die MSI-Installationsroutine
unterstützt die Silent-Installation. Mit dem folgenden Befehl in der Befehlszeile können
Sie PDFlib zum Beispiel ohne Benutzereingaben installieren:
msiexec.exe /I PDFlib-4.0.3.msi /qn
Eine vollständige Liste aller Befehlszeilenparameter finden Sie in der Dokumentation
zum Microsoft Windows Installer.
2.2.4 Anwendungsszenarien
Einsatz der PDFlib-ActiveX-Komponente auf dem Server eines ISP. Die Installation von
Software auf dem Server eines Internet Service Provider (ISP) ist in der Regel wesentlich
schwieriger als auf einem lokalen Rechner, da ISPs oft sehr widerwillig reagieren, wenn
Kunden neue Software installieren möchten. PDFlib ist sehr ISP-freundlich, da sie weder
Dateien im Windows-Verzeichnis noch zwingend Registrierungseinträge benötigt:
> Es ist nur eine einzige DLL nötig, die sich in einem beliebigen Verzeichnis befinden
kann. Diese DLL muss nur mit regsvr32 korrekt registriert worden sein.
> Standardmäßig werden nur ein paar wenige private Einträge in der Registrierung
vorgenommen, die sich unter HKEY_LOCAL_MACHINE\SOFTWARE\PDFlib befinden.
Diese Einträge können auch manuell vorgenommen werden.
> PDFlib kann sogar ohne jegliche private Einträge in der Registrierung verwendet
werden. Der Benutzer muss die fehlenden Einträge dann durch geeignete Aufrufe
19
der Funktion set_parameter( ) kompensieren und damit die Parameter prefix,
resourcefile und serial setzen.
Eine Dateiliste finden Sie im nächsten Abschnitt.
PDFlib-ActiveX-Komponente als Bestandteil des eigenen Produkts. Wenn Sie als Entwickler eine Runtime-Lizenz für PDFlib erworben haben und PDFlib als Bestandteil Ihres
eigenen Produkts ausliefern wollen, müssen Sie die PDFlib-Installation entweder komplett ausliefern und die PDFlib-Installationsroutine als Teil des Produkt-Setups ablaufen lassen oder aber folgende Schritte durchführen:
> Integrieren Sie die PDFlib-Dateien, die bei der Option Runtime installiert werden, in
eine eigene Installation (siehe auch Abschnitt 2.2.3, »Silent-Installation«, Seite 18).
Die von PDFlib benötigten Dateien lassen sich durch einen Blick in das Installationsverzeichnis ermitteln, da nur dort Dateien installiert werden. Die mitgelieferten
AFM-Dateien werden nur dann benötigt, wenn die 14 Standardschriften mit anderen
Encodings als winansi (bzw. builtin bei den Fonts Symbol und ZapfDingbats) verwendet werden sollen (siehe Abschnitt 3.3.1, »Die PDF-Standardschriften«, Seite 46).
> Vergessen Sie keinen der erforderlichen PDFlib-Registrierungsschlüssel. Dazu können Sie die Einträge in der mitgelieferten Registrierungsdateivorlage pdflib.reg ergänzen und diese bei der Installation Ihres eigenen Produkts verwenden.
> Zur Selbstregistrierung muss pdflib_com.dll (zum Beispiel über regsvr32) aufgerufen
werden. Wurde Ihre Installationsroutine mit InstallShield erstellt, können Sie dies
einfach bewerkstelligen, indem Sie die Eigenschaft Self-Registered für die InstallShield-Gruppe, die pdflib_com.dll enthält, auf true setzen.
> Übergeben Sie Ihre Seriennummer zur Laufzeit mit der PDFlib-Funktion set_
parameter( ), wobei Sie serial als ersten Parameter und den String mit der Seriennummer als zweiten Parameter übergeben (siehe auch Abschnitt 0, »Anwendung des
PDFlib-Lizenzschlüssels«, Seite 7:
oPDF.set_parameter("serial", "...Ihre Seriennummer...")
2.2.5 Fehlerbehandlung in ActiveX
Die Fehlerbehandlung für die PDFlib-ActiveX-Komponente erfolgt entsprechend der
COM-Konventionen: Tritt eine PDFlib-interne Exception auf, wird eine COM-Exception
ausgelöst, die den PDFlib-Fehlercode und eine Beschreibung des Fehlers enthält. Außerdem wird der vom PDFlib-Objekt belegte Speicher freigegeben. Tabelle 2.3 gibt eine
Übersicht über alle von PDFlib ausgelösten COM-Fehler sowie die entsprechenden
PDFlib-Exceptions. ActiveX-Programmierer haben mit den Fehlernummern zum Glück
nicht direkt zu tun, da die Type-Library PDFlib_com in der Klasse PDFlib_com.Errors symbolische Konstanten dafür enthält.Die COM-Exception kann im PDFlib-Client abgefangen und auf die Art bearbeitet werden, die die Client-Umgebung für COM-Fehler vorsieht.
Die in COM verwendeten Fehlercodes sind 32-Bit-Werte, deren höchstes Bit gesetzt
ist. Sie erscheinen deshalb als sehr große negative Zahlen. PDFlib hält sich an die COMKonventionen und gibt Fehlercodes zurück, die in dem Bereich liegen, der für anwendungsspezifische Fehler reserviert ist. Genauer betrachtet, haben die Fehlercodes folgenden Aufbau:
COM-Fehlercode = &H80040000 + &H200 + (PDFlib-Fehlercode)
20
Tabelle 2.3 Von PDFlib ausgelöste COM-Exceptions
PDFlib-Fehlername
Dezimalwert Hexadezimalwert
Erklärung
MemoryError
-2147220991
&H80040201
nicht ausreichend Speicher
IOError
-2147220990
&H80040202
Ein-/Ausgabefehler, zum Beispiel
Festplattenspeicher nicht ausreichend
RuntimeError
-2147220989
&H80040203
falsche Reihenfolge der PDFlib-Funktionsaufrufe
IndexError
-2147220988
&H80040204
Array-Index-Fehler
TypeError
-2147220987
&H80040205
Argumenttyp-Fehler
DivisionByZero
-2147220986
&H80040206
Division durch Null
OverflowError
-2147220985
&H80040207
arithmetischer Überlauf
Syntaxfehler
SyntaxError
-2147220984
&H80040208
ValueError
-2147220983
&H80040209
ein an PDFlib übergebenes Argument ist ungültig
SystemError
-2147220982
&H8004020A
interner PDFlib-Fehler
NonfatalError
-2147220981
&H8004020B
ein kleineres Problem ist aufgetreten (Warnung)
UnknownError
-2147220980
&H8004020C
anderer Fehler
(Die erste Hexadezimalzahl entspricht der Visual-Basic-Konstanten vbObjectError und
die zweite dem von Microsoft vorgesehenen Offset für komponentenspezifische Fehler.)
2.2.6 Versionskontrolle in ActiveX
Statt einfacher Major- und Minor-Versionsnummern implementiert COM das Konzept
eines global eindeutigen Identifier (GUID) für eine Class-ID, der eine bestimmte Programmierschnittstelle eindeutig beschreibt. Statt sich mit verschiedenen Versionsnummern herumzuschlagen, kann eine neue Software-Version entscheiden, ob eine bestimmte Schnittstelle, die über ihre GUID identifiziert wird, weiter unterstützt werden
soll oder nicht.
PDFlib_com nutzt als ActiveX-Komponente den Class-ID-Mechanismus. Der GUID für
PDFlib_com ist in deren Type-Library enthalten (welche wiederum in pdflib_com.dll enthalten ist) sowie in der Windows-Registrierung. Da PDFlib sowohl unter dem generischen Programm-Identifier (ProgID) PDFlib_com.PDF als auch unter einer versionsspezifischen ProgID registriert ist, werden Benutzer kaum direkt mit dem GUID zu tun
bekommen.
2.2.7 Unicode-Unterstützung in ActiveX
32-Bit-Versionen von ActiveX/COM bieten native Unicode-Unterstützung. Der ActiveXSprachwrapper konvertiert automatisch alle COM-Strings in Unicode oder ISO Latin 1
(PDFDocEncoding). Die Unicode-Fähigkeit von ActiveX kann jedoch zu subtilen Problemen mit 8-Bit-Encodings (wie zum Beispiel winansi) und Unicode-Zeichen in literalen
Strings führen. Ausführliche Informationen hierzu finden Sie in Abschnitt 3.3.9, »Unicode-Unterstützung«, Seite 65. Wenn Sie die Unicode-Unterstützung von PDFlib mit
ActiveX einsetzen möchten, müssen Sie den Unicode-Modus aktivieren, indem Sie den
Parameter nativeunicode auf true setzen (siehe die Beispiele in den nächsten Abschnitten).
21
2.2.8 Einsatz von PDFlib mit Active Server Pages
Besondere Hinweise zu Active Server Pages1. Beim Einsatz externer Dateien (zum Beispiel Rasterbilddateien) muss die Funktion MapPath von ASP verwendet werden, um die
Namen von Pfaden auf der lokalen Festplatte auf Pfade abzubilden, die in ASP-Skripten
nutzbar sind. Wenn Sie noch keine Erfahrungen mit MapPath haben, sollten Sie sich die
mit PDFlib ausgelieferten ASP-Beispiele ansehen oder die ASP-Dokumentation zu Rate
ziehen. Außerdem sollten Sie in ASP-Skripten keine absoluten Pfadnamen verwenden,
da diese ohne MapPath unter Umständen nicht funktionieren.
Wenn Sie von PDFlib-ASP-Skripten aus auf Dateien zugreifen, die sich auf einem anderen Rechner befinden, dürfen Sie keine UNC-Pfadnamen verwenden, da diese in ASP
nicht funktionieren. Stattdessen müssen Sie in IIS ein neues virtuelles Verzeichnis eintragen. Dazu geben Sie im Administrationstool auf der Registerkarte Basisverzeichnis unter Netzwerkfreigabe auf einem anderen Computer den UNC-Namen an. Danach ist das
entfernte Verzeichnis als virtuelles Verzeichnis in IIS verfügbar.
Das Verzeichnis mit Ihren ASP-Skripten muss die Ausführen-Berechtigung besitzen,
und außerdem die Schreiben-Berechtigung, sofern die PDF-Ausgabe nicht im Arbeitsspeicher (in-core) erzeugt wird (die mitgelieferten ASP-Beispiele generieren PDF alle im
Arbeitsspeicher).
Sie können die Ausführung von COM-Objekten wie PDFlib_com auf Active Server Pages beschleunigen, indem Sie das Objekt außerhalb des eigentlichen Skriptcodes auf der
ASP-Seite instantiieren, womit der Geltungsbereich des Objekts von der Seite auf die Sitzung ausgeweitet wird. Genauer gesagt, verwenden Sie zur Erstellung des Objekts
PDFlib_com dann statt CreateObject (wie es im Beispiel im nächsten Abschnitt gezeigt
wird):
<%@ LANGUAGE = "JavaScript" %>
<%
var oPDF;
oPDF = Server.CreateObject("PDFlib_com.PDF");
oPDF.open_file("");
...
das Tag OBJECT mit den Attributen RUNAT, ID und ProgID:
<OBJECT RUNAT=Server ID=oPDF ProgID="PDFlib_com.PDF"> </OBJECT>
<%
oPDF.open_file("");
...
Sie können die Geschwindigkeit noch weiter steigern, indem Sie das geschilderte Verfahren mit dem Attribut Scope=Application auf die Datei global.asa anwenden, womit der
Geltungsbereich des Objekts auf die Anwendung ausgeweitet wird. Weitere ASP-Beispiele finden Sie in der PDFlib-Distribution.
1. Active Server Pages ist ein Verfahren zur Ausführung von Skripten in verschiedenen Sprachen auf dem Server. Es ist in
Webservern von Microsoft und verschiedenen anderen Server-Produkten verfügbar. Weitere Informationen zu ASP finden
Sie unter http://msdn.microsoft.com/workshop/server/default.asp.
22
Das Beispiel »Hello world« für Active Server Pages (ASP) mit JScript1. Bei den ASPBeispielen erstellen wir keine PDF-Ausgabedatei, sondern generieren die PDF-Daten im
Speicher und senden sie über HTTP direkt an den Client. Dieses Verfahren ist in einer
Webserver-Umgebung wesentlich sinnvoller.
<%
var font;
var oPDF;
oPDF = Server.CreateObject("PDFlib_com.PDF");
if (oPDF == null) {
Response.write("Couldn't create PDFlib object!");
Response.end();
}
// Open new PDF file
oPDF.open_file("");
oPDF.set_info("Creator", "hello.js.asp");
oPDF.set_info("Author", "Thomas Merz");
oPDF.set_info("Title", "Hello, world (ActiveX/ASP/JScript)!");
// start a new page
oPDF.begin_page(595, 842);
font = oPDF.findfont("Helvetica-Bold", "winansi", 0);
oPDF.setfont(font, 24);
oPDF.set_text_pos(50, 700);
oPDF.show("Hello, world!");
oPDF.continue_text("(says ActiveX/ASP/JScript)");
oPDF.end_page();
oPDF.close();
Response.Expires = 0;
Response.Buffer = true;
Response.ContentType = "application/pdf";
Response.Addheader("Content-Disposition", "inline; filename=" +
"hello.js.asp.pdf");
Response.BinaryWrite(oPDF.get_buffer());
Response.End();
%>
Das Beispiel »Hello world« für Active Server Pages (ASP) mit VBScript
<%@ LANGUAGE = VBScript %>
<%
Option Explicit
1. JScript ist eine Erweiterung von ECMAScript (siehe http://www.ecma.ch/stand/ecma-262.htm), das wiederum auf Netscapes JavaScript basiert. Weitere Informationen zu JScript finden Sie unter http://msdn.microsoft.com/scripting/jscript/
default.htm.
23
Dim font
Dim oPDF
Dim buf
Set oPDF = Server.CreateObject("PDFlib_com.PDF")
if not isObject(oPDF) Then
Response.write "Couldn't create PDFlib object!"
Response.end
End If
' Open new PDF file
oPDF.open_file ""
oPDF.set_info "Creator", "hello.vbs.asp"
oPDF.set_info "Author", "Thomas Merz"
oPDF.set_info "Title", "Hello, world (Active X/ASP/VBScript)!"
' start a new page
oPDF.begin_page 595, 842
font = oPDF.findfont("Helvetica-Bold", "winansi", 0)
oPDF.setfont font, 24
oPDF.set_text_pos 50, 700
oPDF.show "Hello, world!"
oPDF.continue_text "(says ActiveX/ASP/VBScript)"
oPDF.end_page
oPDF.close
buf = oPDF.get_buffer()
Response.Expires = 0
Response.Buffer = true
Response.ContentType = "application/pdf"
Response.Addheader "Content-Disposition", "inline; filename=" &
"hello.vbs.asp.pdf"
Response.Addheader "Content-Length", LenB(buf)
Response.BinaryWrite(buf)
Response.End()
Set oPDF = nothing
%>
Fehlerbehandlung in JScript. JScript bietet in Version 5.01 erstmalig eine strukturierte
Ausnahmebehandlung, ähnlich wie in C++ oder Java. JScript-Exceptions lassen sich jedoch nicht typisieren, und eine Exception kann nur von einer einzigen Klausel bearbeitet werden. Die Erkennung und Reaktion auf eine Exception erfolgt über eine try ... catch
Klausel:
try {
...PDFlib-Anweisungen...
} catch (exc) {
1. JScript 5.0 ist in Microsoft Internet Explorer 5.0 und Microsoft Internet Information Services 5.0 verfügbar.
24
Response.write("Error " + exc.number + ": " + exc.description);
Response.end();
}
Hinweis Wegen Problemen in der Integer-Behandlung von JScript können Exception-Nummern nicht direkt mit Hexadezimalwerten verglichen werden. Ein Vergleich mit Dezimalwerten funktioniert
aber einwandfrei.
Fehlerbehandlung in VBScript. Leider verfügt VBScript über keinerlei Mechanismen
zum Abfangen von Fehlern, man kann sie lediglich ignorieren. Um festzustellen, ob bei
vorangegangenen Aufrufen der ActiveX-Komponente ein Fehler auftrat, muss man das
ERR-Objekt in regelmäßigen Abständen überprüfen. Da es in VBScript keine On Error
GoTo Klausel gibt, muss man den Skriptcode mit Aufrufen der Fehlerüberprüfungsroutine spicken oder man riskiert, dass zwischen dem ersten Fehler und dem Aufruf der
Fehlerüberprüfung weitere Fehler auftreten:
On Error Resume Next
Err.Clear
CheckPDFError
...weitere PDFlib-Anweisungen...
Sub CheckPDFError()
If Err.number <> 0 then
WScript.Echo "Error " & Hex(Err.number) & ": " & Err.description
Err.Clear
End If
end Sub
Unicode-Unterstützung in JScript. JScript bietet interne Unicode-Unterstützung. Unicode-Zeichen können direkt in String-Literale geschrieben werden, wobei sie als EscapeSequenz eingegeben werden, zum Beispiel:
oPDF.set_parameter("nativeunicode", "true");
Unicodetext = "\u039B\u039F\u0393\u039F\u03A3";
Alternativ können sie mit der Methode String.fromCharCode aus numerischen Werten
zusammengesetzt werden, zum Beispiel:
Unicodetext = String.fromCharCode(0x39B, 0x39F, 0x393, 0x39F, 0x3A3);
Unicode-Unterstützung in VBScript. VBScript bietet interne Unicode-Unterstützung.
Ähnlich wie in Visual Basic können Unicode-Strings mit der Funktion ChrW aus numerischen Werten zusammengesetzt werden, zum Beispiel:
oPDF.set_parameter "nativeunicode", "true"
Unicodetext = ChrW(&H39B) & ChrW(&H39F) & ChrW(&H393) & ChrW(&H39F) & ChrW(&H3A3)
25
2.2.9 Einsatz von PDFlib mit Visual Basic
Besondere Hinweise für Visual Basic1. Bei externen ActiveX-Komponenten unterstützt Visual Basic sowohl frühe Bindung (zur Kompilierzeit) als auch späte Bindung
(zur Laufzeit). Bei PDFlib sind zwar beide Bindungsarten erlaubt, die frühe Bindung ist
jedoch eindeutig vorzuziehen. Dazu sind folgende Schritte erforderlich:
> Erstellen Sie über Project, References... eine Referenz von Ihrem VB-Projekt auf PDFlib
und selektieren Sie das Control PDFlib_com.
> Deklarieren Sie Objektvariablen vom Typ PDFlib_com.PDF statt vom generischen Typ
Object:
Dim oPDF As PDFlib_com.PDF
Set oPDF = CreateObject("PDFlib_com.PDF")
' oder: Set oPDF = New PDFlib_com.PDF
Die Erstellung einer Referenz und die Verwendung der frühen Bindung bringen mehrere Vorteile mit sich:
> VB kann den Code auf Schreibfehler überprüfen.
> IntelliSense (automatische Befehlsergänzung) und kontextsensitive Hilfe sind verfügbar.
> Der VB-Objektbrowser zeigt alle PDFlib-Methoden mit ihren Parametern und einer
Kurzbeschreibung an.
> VB-Programme sind viel schneller mit früher als mit später Bindung.
Die PDFlib-Programmierung in Visual Basic ist – abgesehen von einer Ausnahme – einfach. Aufgrund eines von Microsoft bestätigten Fehlers in Visual Basic 6 können einige
PDFlib-Funktionen nicht direkt verwendet werden, da Visual Basic die Namen einiger
PDFlib-Methoden fälschlicherweise mit integrierten VB-Methoden überschreibt. Die
folgende Zeile lässt sich in VB 6 beispielsweise nicht erfolgreich kompilieren:
oPDF.circle 10, 10, 30
Zur Umgehung dieses Problems schlug der technische Support von Microsoft folgende
Variante vor:
oPDF.[circle] 10, 10, 30
Der Trick dabei sind die eckigen Klammern um den Methodennamen. Von dem Problem sind nur die beiden folgenden PDFlib-Funktionen betroffen:
circle
scale
In der ActiveX-Komponente von PDFlib ist der Datentyp integer eine vorzeichenbehaftete 32-Bit-Zahl. In Visual Basic entspricht dies dem Datentyp long. Verlangt die PDFlibAPI-Referenz also ein Argument vom Typ int, müssen Visual-Basic-Programmierer den
Typ long verwenden (obwohl VB auch bei int-Argumenten korrekt kompiliert).
1. Visual Basic ist ein kommerzielles Produkt von Microsoft. Weitere Informationen finden Sie unter
http://msdn.microsoft.com/vbasic/prodinfo.
26
Das Beispiel »Hello world« in Visual Basic
Attribute VB_Name = "hello"
Option Explicit
Sub main()
Dim ret As Long, font As Long
Set oPDF = New PDFlib_com.PDF
' Open new PDF file
ret = oPDF.open_file("hello_ax_vb.pdf")
If (ret = -1) Then
MsgBox "Couldn't open PDF file!"
End
End If
oPDF.set_info "Creator", "hello.bas"
oPDF.set_info "Title", "Hello, world (ActiveX/VB)!"
' start a new page
oPDF.continue_text "(says ActiveX/VB)"
oPDF.end_page
oPDF.close
' finish page
' close PDF document
set oPDF = Nothing
End Sub
Fehlerbehandlung in Visual Basic. Ein Visual-Basic-Programm kann Fehler erkennen
und darauf reagieren. Exceptions werden in Visual Basic mit der Klausel On Error GoTo
abgefangen:
Sub main()
On Error GoTo ErrExit
End
ErrExit:
MsgBox Hex(Err.Number) & ": " & Err.Description
End Sub
Unicode-Unterstützung in Visual Basic. Visual Basic bietet interne Unicode-Unterstützung. (Der Programmeditor von Visual Basic scheint jedoch nicht vollständig Unicode-
27
fähig zu sein.) Unicode-Strings können mit der Funktion ChrW aus numerischen Werten
zusammengesetzt werden:
oPDF.set_info "nativeunicode", "true"
2.2.10 Einsatz von PDFlib mit Windows Script Host
Windows Script Host1 unterstützt JScript und VBScript, die wir bereits ausführlich in Abschnitt 2.2.8, »Einsatz von PDFlib mit Active Server Pages«, Seite 22, besprochen haben.
Wir zeigen hier deshalb nur noch das »Hello world«-Beispiel für VBScript.
Das Beispiel »Hello world« für Windows Script Host (WSH) mit VBScript
' hello.vbs
'
' PDFlib client: hello example for ActiveX with Windows Script Host and VBS
' Requires the PDFlib ActiveX component
'
Option Explicit
On Error Resume Next
Dim font
Dim oPDF
Set oPDF = CreateObject("PDFlib_com.PDF")
' Open new PDF file
if (oPDF.open_file("hello_ax_vbs.pdf") = -1) then
WScript.Echo "Couldn't open PDF file!"
WScript.Quit(1)
end if
oPDF.set_info "Creator", "hello.asp"
oPDF.set_info "Title", "Hello, world (Active X/VBS)!"
' start a new page
oPDF.continue_text "(says ActiveX/VBS)"
oPDF.end_page
oPDF.close
set oPDF = Nothing
1. WSH ist mit Befehlszeile (cscript.exe) oder mit Fensteroberfläche (wscript.exe) verfügbar. Es ist in Microsoft Internet Explorer 5, Windows 98, 2000 und XP enthalten. Weitere Informationen finden Sie unter http://msdn.microsoft.com/
scripting.
28
2.2.11 Einsatz von PDFlib mit ColdFusion
Besondere Hinweise zu ColdFusion1. ColdFusion für Windows unterstützt COMObjekte wie PDFlib über das Tag CFOBJECT. Nach der Installation (und damit Registrierung) der PDFlib-ActiveX/COM-Edition kann PDFlib aus ColdFusion heraus ohne weitere Maßnahmen verwendet werden. Da wir mit ColdFusion keine Möglichkeit fanden,
PDF im Speicher zu generieren und an den Client zu übertragen, erzeugt das folgende
Beispiel eine temporäre PDF-Datei. Gemäß der ColdFusion-Dokumentation müssen
Funktionen, die keine Argumente erfordern (zum Beispiel save), mit einem leeren Klammernpaar geschrieben werden.
Hinweis PDFlib unterstützt gegenwärtig nur die Windows-Version von ColdFusion.
Das Beispiel »Hello world« für ColdFusion
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<title>PDFlib ColdFusion sample</title>
</head>
<body>
<CFOBJECT type="COM" name="oPDF" class="PDFlib_com.PDF" action="CREATE">
<CFSET tmp_file=GetTempFile("C:\\tmp\\", "hello_cfm.pdf")>
<CFSET res=oPDF.open_file(tmp_file)>
<CFIF res is -1>
Couldn't open PDF file!
<CFABORT/>
</CFIF>
<CFSET oPDF.set_info("Creator", "hello.cfm")>
<CFSET oPDF.set_info("Author", "Thomas Merz")>
<CFSET oPDF.set_info("Title", "Hello, world (ActiveX/ColdFusion)")>

<CFSET oPDF.begin_page(595, 842)>
<CFSET font = oPDF.findfont("Helvetica-Bold", "winansi", 0)>
<CFSET oPDF.setfont(font, 24)>
<CFSET oPDF.set_text_pos(50, 700)>
<CFSET oPDF.show("Hello, world!")>
<CFSET oPDF.continue_text("(says ActiveX/ColdFusion)")>
<CFSET oPDF.end_page()>
<CFSET oPDF.close()>
<CFCONTENT TYPE="application/pdf" FILE="#tmp_file#" DELETEFILE="yes">
</body>
</html>
1. Siehe http://www.macromedia.com/software/coldfusion
29
Um das PDF-Dokument in einer Datei auf der Festplatte zu speichern, können Sie nach
dem Aufruf von close( ) folgende Zeile einsetzen:
<CFFILE action="COPY" source="#tmp_file#" destination="c:\document1.pdf">
Fehlerbehandlung in ColdFusion. ColdFusion unterstützt eine strukturierte Ausnahmebehandlung, die für COM-Exceptions von PDFlib herangezogen werden kann. Die
von PDFlib gelieferte Fehlermeldung kann über die ColdFusion-Variable CFCATCH.detail
abgefragt werden. Um PDFlib-Exceptions im ColdFusion-Code abzufangen, können Sie
das folgende Fragment als Basis verwenden:
<CFTRY>
<CFCATCH>
<CFOUTPUT>
Abgefangene PDFlib-Exception: #CFCATCH.detail#
<CFABORT/>
</CFOUTPUT>
</CFCATCH>
</CFTRY>
Unicode-Unterstützung in ColdFusion. Da wir in ColdFusion keinerlei Unicode-Unterstützung fanden, ist die PDFlib-Funktionalität zur automatischen Unicode-Konvertierung nicht verfügbar. ColdFusion-Entwickler müssen Unicode-Strings manuell zusammenstellen (siehe Abschnitt 3.3.9, »Unicode-Unterstützung«, Seite 65).
2.2.12 Einsatz von PDFlib mit Borland Delphi
Besondere Hinweise zu Borland Delphi1. Um PDFlib mit Delphi 5 oder 6 einzusetzen,
müssen Sie die PDFlib-Type-Library in Ihrem Projekt wie folgt referenzieren: Klicken Sie
auf Project, Import Type Library... und wählen Sie PDFlib aus der Liste (erscheint der Eintrag PDFlib nicht, dann klicken Sie auf Hinzufügen..., um die Datei pdflib_com.dll von der
Festplatte zu selektieren). Wählen Sie einen beliebigen Eintrag in Palette page und klicken Sie auf Install.... Diese Schritte müssen Sie pro Delphi-Installation nur einmal
durchführen (nicht für jedes einzelne Projekt).
Das Beispiel »Hello world« für Borland Delphi
unit hello;
interface
uses Windows, Classes, Forms, Dialogs, ExtCtrls, Controls, StdCtrls,
PDFlib_com_TLB, OleServer;
type
TForm1 = class(TForm)
Panel1: TPanel;
InsertBtn: TButton;
pdf: TPDF;
procedure InsertBtnClick(Sender: TObject);
end;
1. Siehe http://www.borland.com/delphi
30
var
Form1: TForm1;
implementation
{$R *.DFM}
procedure TForm1.InsertBtnClick(Sender: TObject);
var
f: Integer;
begin
if pdf.open_file('hello_delphi.pdf') = -1 then begin
ShowMessage('Couldn´t open hello_delphi.pdf!');
Exit;
end;
pdf.set_info('Creator', 'hello.pas');
pdf.set_info('Author', 'Rainer Schaaf');
pdf.set_info('Title', 'Hello World (Delphi)');
pdf.begin_page(595,842);
f := pdf.findfont('Helvetica-Bold', 'host', 0);
pdf.setfont(f, 18.0);
pdf.set_text_pos(50, 700);
pdf.show('Hello World');
pdf.continue_text('(says Delphi)');
pdf.end_page;
pdf.close;
end;
end.
Fehlerbehandlung in Borland Delphi. Delphi unterstützt eine strukturierte Ausnahmebehandlung, die für Exceptions von OLE-Objekten wie PDFlib herangezogen werden
kann. Um PDFlib-Exceptions im Delphi-Code abzufangen, können Sie das folgende Fragment als Basis verwenden:
uses SysUtils;
...
try
except
On E: Exception do begin
ShowMessage(E.Message);
end;
end;
Unicode-Unterstützung in Borland Delphi. Delphi bietet mit dem Datentyp WideString
native Unicode-Unterstützung. Um die PDFlib-Unicode-Unterstützung in Delphi zu
nutzen, müssen Sie Strings vom Typ WideString verwenden:
unicodetext: WideString;
...
31
pdf.set_parameter('nativeunicode', 'true');
unicodetext := #$039B;
2.3 C-Sprachbindung
(Dieser Abschnitt ist in der vorliegenden Ausgabe des PDFlib-Referenzhandbuchs nicht
enthalten.)
2.4 C++-Sprachbindung
enthalten.)
2.5 Java-Sprachbindung
enthalten.)
2.6 .NET-Sprachbindung
2.6.1 Arbeitsweise
Die .NET-Architektur1 von Microsoft unterstützt zahlreiche Programmiersprachen, wobei sie sich auf die Common Language Runtime (CLR) stützt, die eine allgemeine Umgebung zur Ausführung von Programmen bereitstellt.
Die .NET-Edition von PDFlib unterstützt alle wesentlichen .NET-Konzepte. Technisch
gesehen handelt es sich bei der .NET-Edition von PDFlib um eine gemanagte C++-Klasse
(mit einem gemanagten Wrapper um die PDFlib-Kernbibliothek), die unter Kontrolle
des .NET-Frameworks abläuft. Diese Klasse wird als statische Assembly mit einem starken Namen (strong name) ausgeliefert. Die PDFlib-Assembly (pdflib_dotnet.dll) enthält
die Bibliothek selbst sowie zusätzliche Metainformationen.
2.6.2 Installation von PDFlib.NET
PDFlib.NET kann in allen Umgebungen, die das .NET-Framework unterstützen, verwendet werden. Wir zeigen Beispiele für folgende Umgebungen:
> C#
> Visual Basic .NET
Auch andere Entwicklungsumgebungen für .NET werden von PDFlib unterstützt, wenngleich wir dafür keine eigenen Beispiele anführen.
Voraussetzungen zur Installation von PDFlib.NET. Die Installation ist einfach durchzuführen. Beachten Sie dabei folgendes:
> Vor der Installation von PDFlib.NET muss selbstverständlich die Installation des
.NET-Frameworks erfolgen.
1. Siehe http://msdn.microsoft.com/vstudio
32
> PDFlib.NET benötigt selbst weder eine spezielle Windows-Version noch ein bestimmtes Service-Pack.
Die MSI-Installationsroutine von PDFlib.NET installiert die PDFlib-Assembly einschließlich der zugehörigen Dateien (vorwiegend Dokumentation und Beispiele) interaktiv auf
dem Rechner.
Installation von PDFlib.NET im Global Assembly Cache. Der Global Assembly Cache ist
ein zentraler Ablageort für .NET-Komponenten. PDFlib wird nicht automatisch im GAC
installiert, Sie können dies aber manuell mit dem Hilfsprogramm gacutil (das zu Visual
Studio .NET gehört) bewerkstelligen. Dazu verwenden Sie folgenden Befehl:
gacutil.exe /i "C:\Program Files\PDFlib\PDFlib.NET 4.0.3\bin\PDFlib_dotnet.dll"
Mit demselben Befehl, jedoch der Option /u, können Sie PDFlib aus dem GAC deinstallieren. Alternativ zu gacutil können Sie das Microsoft .NET Framework Configuration Tool verwenden, das Bestandteil des .NET Framework SDK ist.
2.6.3 Silent-Installation
Die MSI-Installationsroutine unterstützt auch die Silent-Installation. Mit folgendem Befehl können Sie PDFlib zum Beispiel ohne jede Benutzerinteraktion von der Befehlszeile
aus installieren:
msiexec.exe /I PDFlib.NET-4.0.3.msi /qn
Eine vollständige Liste der Befehlszeilenoptionen finden Sie in der Dokumentation zum
Microsoft Windows Installer.
Außerdem wird ein Verfahren namens xcopy deployment unterstützt. Dabei können
Sie die PDFlib-Assembly (pdflib_dotnet.dll) einfach mit dem xcopy-Befehl oder per FTP
auf den Server kopieren.
2.6.4 Fehlerbehandlung in .NET
PDFlib.NET unterstützt .NET-Exceptions und löst eine Exception mit detaillierter Fehlermeldung aus, sobald ein Laufzeitproblem auftritt. Der Client ist für das Abfangen der
Exception und eine angemessene Reaktion zuständig. Anderenfalls fängt das .NETFramework die Exception ab, was gewöhnlich zum Beenden der Anwendung führt.
Um Informationen über die Exception zu übermitteln, definiert PDFlib eine eigene
Exception-Klasse namens PDFlib_dotnet.PDFException mit den Members msg und type.
2.6.5 Versionskontrolle in .NET
PDFlib.NET unterstützt das .NET-Standardversionierungsschema mit Major-, Minor-,
Build- und Revisionsnummer. Die Major-, Minor- und Build-Versionsnummer enthält
jedoch die Major-, Minor- und Patchlevel-Versionsnummer von PDFlib.
2.6.6 Unicode-Unterstützung in .NET
Das .NET-Framework bietet native Unicode-Unterstützung. Die Wrapperklasse
PDFlib.NET konvertiert automatisch alle .NET-Strings nach Unicode bzw. ISO Latin 1
(PDFDocEncoding). Die Unicode-Fähigkeit von .NET kann jedoch zu ernsthaften Proble-
33
men bei 8-Bit-Zeichensätzen (wie zum Beispiel winansi) sowie Unicode-Zeichen in literalen Strings führen. Einzelheiten hierzu finden Sie in Abschnitt 3.3.9, »Unicode-Unterstützung«, Seite 65. Um die Unicode-Unterstützung von PDFlib mit .NET nutzen zu
können, aktivieren Sie den Unicode-Modus, indem Sie den Parameter nativeunicode auf
true setzen.
2.6.7 Einsatz von PDFlib mit C#
Spezielle Hinweise zu C#. Um PDFlib.NET in Ihrem C#-Projekt nutzen zu können,
müssen Sie in Visual C# .NET eine Referenz auf die PDFlib.NET-Assembly erzeugen.
Dazu klicken Sie auf Project, Add Reference..., Browse... und wählen PDFlib_dotnet.dll aus
dem Installationsverzeichnis.
Mit dem Befehlszeilencompiler können Sie PDFlib.NET wie folgt referenzieren:
csc.exe /r:..\..\bin\PDFlib_dotnet.dll hello.cs
Das Beispiel »Hello world« in C#.
using System;
using System.Text;
using PDFlib_dotnet;
class Hello {
static void Main(string[] args) {
PDF p;
int font;
p = new PDFlib();
// Open new PDF file
if (p.open_file("hello.pdf") == -1)
{
Console.WriteLine("Error: cannot open PDF file 'hello.pdf'.\n");
return;
}
p.set_info("Creator", "hello.cs");
p.set_info("Author", "Rainer Schaaf");
p.set_info("Title", "Hello, world (.NET/C#)!");
font = p.findfont("Helvetica-Bold", "winansi", 0);
// start a new page
p.begin_page(595, 842);
p.setfont(font, 24);
p.set_text_pos(50, 700);
p.continue_text("Hello, world!");
p.continue_text("(says .NET/C#)");
p.end_page();
// finish page
p.close();
// close PDF document
}
34
// finish the PDFlib Object
}
Fehlerbehandlung in C#. Im Client-Code können von PDFlib ausgelöste .NET-Exceptions mit der üblichen Kombination von try und catch behandelt werden:
try {
} catch (PDFlibException e)
Console.WriteLine("PDFlib-Exception abgefangen:\n{0}", e.msg);
}
Unicode-Unterstützung in C#. Unicode-Strings können in C# durch Übergabe einer
passenden Escape-Sequenz zusammengesetzt werden, zum Beispiel:
p.set_parameter("nativeunicode", "true");
Unicodetext = "\u039B\u039F\u0393\u039F\u03A3";
2.6.8 Einsatz von PDFlib mit Visual Basic .NET
Spezielle Hinweise zu Visual Basic .NET. Um PDFlib.NET in Ihrem VB.NET-Projekt nutzen zu können, müssen Sie in Visual Basic .NET eine Referenz auf die PDFlib.NET-Assembly erzeugen. Dazu klicken Sie auf Project, Add Reference..., Browse... und wählen dann
PDFlib_dotnet.dll aus dem Installationsverzeichnis.
Mit dem Befehlszeilencompiler können Sie PDFlib.NET wie folgt referenzieren.
vbc.exe /r:..\..\bin\pdflib_dotnet.dll hello.vb
Das Beispiel »Hello world« für Visual Basic .NET.
Imports System
Imports PDFlib_dotnet
Class hello
Public Shared Sub Main()
Dim p As PDFlib_dotnet.PDFlib
Dim font As Integer
p = New PDFlib()
' Open new PDF file
If (p.open_file("hello.pdf") = -1) Then
Console.WriteLine("Error: cannot open PDF file 'hello.pdf'")
End
End If
p.set_info("Creator", "hello.vb")
p.set_info("Author", "Rainer Schaaf")
p.set_info("Title", "Hello, world (VB.NET)!")
' start a new page
p.begin_page(595, 842)
font = p.findfont("Helvetica-Bold", "winansi", 0)
35
p.setfont(font, 24)
p.set_text_pos(50, 700)
p.show("Hello, world!")
p.continue_text("(says .NET/VB)")
p.end_page()
p.close()
' finish page
' close PDF document
End Sub
End Class
Fehlerbehandlung in Visual Basic .NET. Visual Basic .NET unterstützt zwei Arten von
Ausnahmebehandlung:
> strukturierte Ausnahmebehandlung (die auch in anderen modernen Sprachen wie
C# verwendet wird)
> traditionelle unstrukturierte Ausnahmebehandlung (die einzig mögliche Ausnahmebehandlung in Visual Basic 6.0)
Der Client-Code kann von PDFlib ausgelöste .NET-Exceptions auf beide der oben erwähnten Arten behandeln, die Syntax ist jedoch unterschiedlich. Wir empfehlen, Exceptions mit strukturierter Ausnahmebehandlung abzufangen. Dazu wird eine try...catchKlausel verwendet:
try
} catch e As PDFlibException
Console.WriteLine("PDFlib-Exception abgefangen:\n{0}", e.msg);
end try
Um Exceptions mit traditioneller unstrukturierter Fehlerbehandlung abzufangen, verwenden Sie eine On Error GoTo-Klausel:
Imports Microsoft.VisualBasic
Public Shared Sub Main()
On Error GoTo ErrExit
Exit Sub
ErrExit:
Console.WriteLine("PDFlib-Exception abgefangen: {0}", Err.Description)
End Sub
Unicode-Unterstützung in Visual Basic .NET. Unicode-Strings können in Visual Basic
.NET mit der Funktion ChrW aus numerischen Werten aufgebaut werden:
Imports Microsoft.VisualBasic
...
p.set_parameter("nativeunicode", "true")
36
2.6.9 PDFlib ist nicht für ASP.NET freigegeben
Obwohl PDFlib.NET für den Einsatz mit ASP.NET konzipiert wurde, können wir den Einsatz der .NET-Edition von PDFlib mit ASP.NET aufgrunds eines Bugs im .NET-Framework,
der von Microsoft bestätigt wurde (Bugnummer Q309694) derzeit nicht empfehlen.
Dieser Framework-Bug betrifft alle Komponenten, die Übergänge von unmanaged to
managed Code enthalten (was bei PDFlib der Fall ist), falls diese in Umgebungen eingesetzt werden, die Application Domains dynamisch laden und wieder entladen (was wiederum bei ASP.NET der Fall ist). Obwohl einfache ASP.NET-Anwendungen mit PDFlib
funktionieren, löst ASP.NET eine Exception vom Typ AppDomainUnloaded aus, sobald eines von mehreren Ereignissen eintritt. Zudiesen Auslösern gehört das Editieren von
Konfigurationsdateien ebenso wie das Erreichen von Grenzen der Speichernutzung
u.a.m. Obwohl diese Auslöser für sich genommen harmlos sind, bewirken, dass die Laufzeitumgebung eine Application Domain entlädt und dynamisch wieder lädt, was obige
Exception auslöst.
Solange dieser Bug im .NET-Framework nicht von Microsoft behoben wurde, raten
wir vom Einsatz von PDFlib.NET mit ASP.NET oder eigenen Applikationen, die AppDomains nutzen, ausdrücklich ab.
2.7 Perl-Sprachbindung
enthalten.)
2.8 PHP-Sprachbindung
enthalten.)
2.9 Python-Sprachbindung
enthalten.)
2.10 RPG-Sprachbindung
vorhanden.)
2.11 Tcl-Sprachbindung
enthalten.)
2.7 Perl-Sprachbindung
37
3 PDFlib- und PDI-Programmierung
3.1 Allgemeine Aspekte
3.1.1 Struktur eines PDFlib-Programms
PDFlib-Anwendungen müssen sich an einige strukturelle Regeln halten, die sehr einfach zu verstehen sind. Es sollte aber keinerlei Probleme bereiten, Anwendungen unter
Einhaltung dieser Bedingungen 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 korrekte PDFlib-Client-Programme, wenn man ein Dokument
einfach auf ganz »natürliche« Art und Weise anlegt.
PDFlib erzwingt die korrekte Reihenfolge von Funktionsaufrufen durch streng definierte Geltungsbereiche (siehe Abschnitt 4.1, »Datentypen, Namenskonventionen und
Geltungsbereiche«, Seite 85). Jede Funktionsbeschreibung enthält auch Angaben über
den jeweiligen Geltungsbereich. Der Aufruf einer Funktion aus einem anderen Geltungsbereich führt unmittelbar zu einer PDFlib-Exception. PDFlib löst außerdem eine
Exception aus, wenn die von einem Bibliotheksclient übergebenen Parameter nicht korrekt sind.
3.1.2 Erzeugung 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 Verfahren ist schneller, da kein Schreiben auf die Festplatte erforderlich ist. Das PDF-Dokument könnte dann zum Beispiel direkt via HTTP übertragen werden. Es dürfte insbesondere 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 verarbeiten (zum Beispiel jedes Mal, wenn eine Seite komplett ist) oder das vollständige PDFDokument am Ende in einem Stück (nach PDF_close( )) verwenden. Die stückweise Generierung und Weiterverarbeitung der PDF-Daten ist in mehrerer Hinsicht vorteilhaft. Erstens sinken die Speicheranforderungen, da die Daten nicht vollständig im Speicher vorgehalten werden müssen. Außerdem lässt sich die Leistung erheblich steigern, 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 Arbeitsspeicher zu generieren, übergeben Sie an PDF_open_file( ) einfach einen leeren Dateinamen und holen die Daten über PDF_get_buffer( ) ab:
oPDF.open_file ("")
...Dokument anlegen...
oPDF.close
' Puffer mit PDF holen und in Datei schreiben
38
Kapitel 3: PDFlib- und PDI-Programmierung (ActiveX/COM- und .NET-Edition)
' Das ist in VB nicht besonders sinnvoll, wohl aber in ASP
Open "file.pdf" For Binary Access Write As #1
Put #1, , oPDF.get_buffer
Close #1
Set oPDF = Nothing
Hinweis Um die PDF-Daten aus dem Puffer zu holen, benötigt man Binärzugriff. Dies ist unter Umständen nicht in allen Umgebungen möglich, da die jeweilige Entwicklungsumgebung gewissen
Einschränkungen unterliegen kann.
3.1.3 Fehlerbehandlung
Eine bestimmte Art von Fehlern wird in vielen Sprachen nicht zu Unrecht 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
besteht darin, konventionelle Verfahren zur Fehlerbenachrichtigung (also besondere
Funktionsrückgabewerte) für Funktionsaufrufe zu verwenden, die häufig zu Fehlern
führen. Besondere Verfahren zur Ausnahmebehandlung setzt man dagegen in selten zu
erwartenden Fällen ein, wo man den Code nicht mit Bedingungen zupflastern möchte.
Diese Methode wird auch von PDFlib verfolgt. So geht man bei manchen Operationen
davon aus, dass sie relativ häufig schiefgehen, zum Beispiel:
> der Versuch, ohne geeignete Berechtigung eine Ausgabedatei zu öffnen
> der Einsatz eines Fonts, für den keine Metrikdaten verfügbar sind
> der Versuch, eine beschädigte Bilddatei zu öffnen
> der Versuch, eine verschlüsselte PDF-Datei zu importieren
PDFlib zeigt solche Fehler durch die Rückgabe eines speziellen Werts an (normalerweise
– 1), der bei den einzelnen Funktionen in Kapitel 4 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 die Bibliothek auf eine solche Ausnahmesituation, wird eine COM-Exception ausgelöst, ohne dass spezielle Werte an die aufrufende Funktion zurückgegeben werden.
PDFlib-Exceptions lassen sich in mehrere Kategorien unterteilen, die in Tabelle 2.3
aufgeführt werden. Der Error-Handler erhält den Typ des PDFlib-Fehlers mit einer beschreibenden Nachricht.
Nicht-fatale Fehlermeldungen (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 diesem Grund lassen sich Warnungen mit folgendem Funktionsaufruf unterbinden:
oPDF.set_parameter "warning", "false"
Als Strategie ist zu empfehlen, Warnungen im Entwicklungsstadium zu aktivieren (und
genau zu untersuchen) und im laufenden Betrieb zu deaktivieren.
3.1 Allgemeine Aspekte
39
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 nach oben. Das Standardkoordinatensystem
kann von PDFlib-Clientprogrammen durch Rotieren, Skalieren, Verschieben oder Scheren modifiziert werden, so dass sich neue benutzerspezifische Koordinaten ergeben. Für
diese Transformationen werden die Funktionen rotate( ), scale( ), translate( ) und skew( )
verwendet. Nach der Transformation müssen alle Koordinaten in Grafik- und Textfunktionen an das neue Koordinatensystem angepasst übergeben werden. Zu Beginn einer
neuen Seite wird wieder auf das Standardkoordinatensystem umgestellt.
Um PDFlib-Anwendern beim Arbeiten mit dem Koodinatensystem von PDF behilflich zu sein, enthält die PDFlib-Distribution die PDF-Datei grid.pdf, die die Koordinaten
für gängige Seitenformate zeigt. Als nützliches Hilfsmittel zur PDFlib-Entwicklung können Sie sich die Seite mit dem für Sie interessanten Format auf eine durchsichtige Folie
ausdrucken. (Verwenden Sie keine billigen Overhead-Folien, da diese kaum hitzebeständig sind und Ihren Laserdrucker ruinieren können!)
Acrobat 5 (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 und nicht, wie in PDF üblich, auf die linke untere Ecke beziehen.
Lassen Sie sich nicht von PDF-Ausdrucken mit scheinbar falschem Seitenformat irritieren. 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 Skalierung des Ausdrucks führt.
> Nicht-PostScript-Druckertreiber können Objekte nicht immer in ihrer exakten Größe
drucken.
Hinweis Koordinatentransformationen haben keinen Einfluss auf Hypertextfunktionen, zum Beispiel
zur Erstellung von Notizen, Verknüpfungen oder Dateianlagen. Diese arbeiten immer mit dem
Standardkoordinatensystem.
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:
oPDF.[scale] 28.3465, 28.3465
Nach diesem Aufruf interpretiert PDFlib alle Koordinaten (außer für Hyptertextfunktionen, siehe oben) in Zentimeter, da 72/2.54 = 28.3465.
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
40
PDFlib-Funktionen zum Drehen, Verschieben, Skalieren und Scheren des Koordinatensystems, diese wirken sich aber nicht auf bereits auf der Seite vorhandene Objekte aus,
sondern nur auf später gezeichnete.
Das folgende Beispiel generiert erst ein wenig horizontalen Text, dann wird das
Koordinatensystem gedreht, um vertikalen Text auszugeben. Das Sichern und Wiederherstellen des Grafikkontexts (mit save/restore) ermöglicht es, nach der Ausgabe des vertikalen Texts ohne weiteres wieder horizontalen Text im ursprünglichen Koordinatensystem auszugeben:
oPDF.show "Dies ist horizontaler Text"
textx = oPDF.get_value("textx", 0)
texty = oPDF.get_value("texty", 0)
oPDF.save
oPDF.translate textx, texty
oPDF.rotate 90
oPDF.show "Vertikaler Text"
oPDF.restore
' Textposition bestimmen
' Textposition bestimmen
' Ursprung an Textende verschieben
' Koordinaten drehen
' Abstand zu horizontalem Text vorsehen
oPDF.continue_text "Weiterer horizontaler Text"
Einsatz von Top-Down-Koordinaten. Im Gegensatz zum Bottom-Up-Koordinatensystem von PDF arbeiten manche grafischen Umgebungen mit Top-Down-Koordinaten.
Wenn Sie diese Art vorziehen, können Sie sich das entsprechende Koordinatensystem
problemlos mit den Transformationsfunktionen von PDFlib einrichten. Da die Transformationen aber auch die Textausgabe beeinflussen, sind weitere Aufrufe erforderlich,
damit der Text nicht gespiegelt erscheint. Das folgende Codefragment zeigt, wie Sie ein
Koordinatensystem mit dem Ursprung in der linken oberen Ecke der Seite einrichten,
wobei die y-Koordinate nach unten zeigt, die übliche Textrichtung aber beibehalten
wird und der Text aufrecht auf der Seite steht:
oPDF.begin_page Width, Height
oPDF.translate 0, Height
oPDF.[Scale] 1, -1
' Seitenformat einrichten
' Koordinatenursprung verschieben
' an horizontaler Achse spiegeln
font = oPDF.findfont("Helvetica-Bold", "host", 0)
oPDF.setfont font, -18
oPDF.set_value "horizscaling", -100
' Beispieltext
' Text aufrecht stellen
' Spiegelung ausgleichen
oPDF.show "Hello world!"
' Top-Down-Koordinaten verwenden
Um Text in einem Textfeld mit der oberen linken Ecke (x, y), der Breite w und der Höhe h
zu formatieren, verwenden Sie die folgende Zeile (dies ist erforderlich, da die Funktion
die Höhe h zur Anfangsposition y addiert und Text mit negativer Schriftgröße in die
entgegengesetzte Richtung läuft):
c = show_boxed(text, x, y-h, w, h, "justify", "")
Ebenso können Sie folgendes Fragment nutzen, um Bilder im Top-Down-Koordinatensystem korrekt zu positionieren:
41
' Bild in linke untere Ecke der Seite platzieren
oPDF.save
oPDF.translate 0, Height
' Ursprung temporär nach links unten verschieben
oPDF.scale 1, -1
oPDF.place_image lImage, 0, 0, 1
oPDF.restore
3.2.2 Begrenzungen für Seiten und Koordinaten
Seitengröße. Im Gegensatz zu PDF und PDFlib, die keinerlei Einschränkungen hinsichtlich der verwendbaren Seitengröße aufweisen, gibt es bei Acrobat-Implementierungen in der Softwarearchitektur begründete Formatbeschränkungen. Andere PDFInterpreter können aber durchaus mit größeren oder kleineren Formaten umgehen. Im
Kompatibilitätsmodus für Acrobat 3 löst PDFlib die Exception PDF_RuntimeError aus,
wenn die für Acrobat 3 spezifischen Grenzen überschritten wurden. Im Kompatibilitätsmodus für Acrobat 4 (Standard) oder Acrobat 5 gibt PDFlib lediglich eine nicht-fatale
Warnung aus, wenn die für Acrobat 4 spezifischen Grenzen überschritten wurden. Tabelle 3.1 zeigt die Einschränkungen bezüglich der Seitengröße in den verschiedenen
Acrobat-Versionen; Abmessungen für Standardseitenformate finden Sie in Tabelle 4.26.
Tabelle 3.1 Minimale und maximale Seitengröße verschiedener PDF-Viewer
PDF-Viewer
Minimale Seitengröße
Maximale Seitengröße
Acrobat 3
1" = 72 pt = 2.54 cm
45" = 3240 pt = 114.3 cm
Acrobat 4 und 5
1/24" = 3 pt = 0.106 cm
200" = 14400 pt = 508 cm
Verschiedene Angaben für die Seitengröße. Im Gegensatz zu vielen PDFlib-Entwicklern, die nur die Höhe und Breite der Seite festlegen, können in speziellen Anwendungen (insbesondere für die Druckvorstufe) zusätzliche Größenangaben wünschenswert
sein. PDFlib unterstützt alle in Acrobat 4/PDF 1.3 spezifizierten Größenangaben. PDFlibClients können folgende Größenangaben verwenden, die in unterschiedlichen Umgebungen sinnvoll sind:
> MediaBox: beschreibt die Größe des Ausgabemediums und entspricht unserer herkömmlichen Vorstellung von der Seitengröße.
> CropBox: gibt an, mit welcher Größe Acrobat die Seite anzeigen soll.
> TrimBox: beschreibt die Größe der (eventuell beschnittenen) Endseite.
> ArtBox: beschreibt den Teilbereich einer PDF-Seite, der für die Montage auf einer anderen Seite gedacht ist.
> BleedBox: gibt an, auf welche Größe die Seite in einer Produktionsumgebung beschnitten werden soll, und berücksichtigt eventuell benötigte Druckformaterweiterungen, die wegen Ungenauigkeiten im Ausgabeprozess nötig sind.
PDFlib verwendet keinen dieser Werte, nimmt sie aber in die Ausgabedatei auf. Standardmäßig wird eine MediaBox entsprechend der für die Seite festgelegten Höhe und
Breite, aber keiner der anderen Einträge erzeugt. Das folgende Codefragment beginnt
eine neue Seite und setzt die vier Werte für die CropBox:
oPDF.set_value "CropBox/llx",
oPDF.set_value "CropBox/lly",
oPDF.set_value "CropBox/urx",
oPDF.set_value "CropBox/ury",
42
' neue Seite beginnen
10
10
500
800
Anzahl der Seiten im Dokument. In PDFlib gibt es keine Begrenzung für die Anzahl der
Seiten in einem Dokument. Im Gegensatz zu früheren PDFlib-Versionen, die bei großen
Dateien eine Ausgabe erzeugten, deren Anzeige in Acrobat sehr langsam war, wurde die
Generierung der PDF-Strukturen in PDFlib 4 dahingehend optimiert, die Navigation
auch bei Dokumenten mit hunderten oder tausenden von Seiten in Acrobat ganz erheblich zu beschleunigen.
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öglichst geringe Dateigröße zu erzeugen. Wie in Tabelle 3.2 ausgeführt, hängt die Genauigkeit von PDFlib von den absoluten Koordinatenwerten ab. Dieser Aspekt kann zwar sehr
häufig ignoriert werden, bei manchen anspruchsvollen Anwendungen ist jedoch darauf
zu achten, bei Skalierungsoperationen die PDF-inhärenten Koordinatengrenzen nicht
zu überschreiten.
Tabelle 3.2 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 vom Typ ValueError
3.2.3 Pfade und Farben
Grafikpfade. 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 Teilpfaden, bestehen. Auf einen Pfad können verschiedene Operationen angewandt werden (siehe Abschnitt 4.4.5, »Zeichnen und Beschneiden von Pfaden«, Seite
104):
> Beim Stroking (Zeichnen) wird der Pfad selbst gezeichnet, wobei die vom Client übergebenen Zeichenparameter 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 Bildbereich für nachfolgende Zeichenoperationen reduziert, 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 PDFDatei, aber unsichtbar ist. Dies wird aber nur selten genutzt.
Es führt zu einem Fehler, wenn Sie einen Pfad konstruieren, ohne eine der obigen Operationen auf ihn anzuwenden. Durch das System der Geltungsbereiche stellt PDFlib sicher, dass sich Clients an diese Einschränkung halten. Alle diesbezüglichen Regeln lassen 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:
43
oPDF.moveto 100, 100
oPDF.lineto 200, 100
oPDF.stroke
Die meisten Grafikfunktionen arbeiten mit dem Konzept eines aktuellen Punkts, den
man sich wie die aktuelle Stiftposition beim Zeichnen vorstellen kann.
Farbe. PDFlib-Clients können die Farben festlegen, die zum Zeichnen und Füllen von
Pfaden und Zeichen verwendet werden sollen. Farben können in mehreren Farbräumen
definiert 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 zwischen 0=keine Farbe und 1=volle Farbe, für Cyan, Magenta, Yellow (Gelb) und Black (Schwarz); (0, 0, 0, 0)=weiß, (0, 0, 0, 1)=schwarz. Beachten Sie die
Unterschiede zur RGB-Definition.
> Schmuckfarbe (Separation-Farbraum): eine Farbe beliebigen Namens mit einer alternativen Darstellung in einem der oben erwähnten Farbräume; sie wird generell für
die Erstellung von Dokumenten verwendet, die auf einer Druckmaschine mit einer
oder mehreren kundenspezifischen Farben gedruckt werden sollen. Der Farbauftrag
liegt zwischen 0=keine Farbe und 1=maximale Intensität der Schmuckfarbe.
> Füllmuster: Kachelung mit einem Objekt, das aus beliebigem Text, Vektorgrafiken
oder Rasterbildern besteht (Füllmuster werden im Kompatibilitätsmodus für Acrobat 3 nicht unterstützt, da sie in Acrobat 3 nicht am Bildschirm angezeigt werden).
Der Standardwert für Linien- und Füllfarbe ist schwarz, das heißt (0, 0, 0) im RGB-Farbraum.
3.2.4 Templates
Templates in PDF. PDFlib unterstützt ein PDF-Merkmal, das technisch form XObjects
heißt. Da diese Bezeichnung jedoch zu leicht mit interaktiven Formularen verwechselt
werden könnte, verwenden wir dafür den Namen 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 einem 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 mehrmals) 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 Ausgabedatei entsprechend verringert. Templates
eignen sich für Elemente, die wiederholt auf mehreren Seiten auftreten, zum Beispiel
ein feststehender Hintergrund, ein Firmenlogo oder grafische Elemente, die aus CADSoftware oder Software für Landkarten stammen. Templates werden zudem häufig für
Schnitt- und Registermarken oder spezielle asiatische Glyphen verwendet.
Wichtige Informationen zu den grafischen Eigenschaften von Templates finden Sie
in Abschnitt 3.5.4, »PDF-Import, Templates und Vererbung des Grafik- und
Textzustands«, Seite 84.
44
Hinweis PDF-Templates sind ein effizientes Mittel, um die Größe einer PDF-Datei zu verringern. Dieser
Vorteil ist leider nicht mehr gegeben, wenn Sie PDF-Dateien, die Templates enthalten, auf einem PostScript-Drucker ausdrucken. Je nach Anzahl der verwendeten Templates müssen Sie
sich dabei auf Druckjobs einstellen, die wesentlich größer sind als die zugehörigen PDF-Dateien.
Einsatz von Templates mit PDFlib. Templates können nur außerhalb einer Seitenbeschreibung definiert, aber innerhalb einer Seitenbeschreibung verwendet werden. Templates 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
place_image( ), genauso wie Sie Bilder auf der Seite platzieren (siehe Abschnitt 3.4.2,
»Häufig benötigte Codefragmente für Rasterbilder«, Seite 74). Das generelle Codefragment hierfür sieht wie folgt aus:
' Template definieren
lTemplate = oPDF.begin_template(template_width, template_height);
...mit Text-, Vektorgrafik- und Rasterbildfunktionen zeichnen...
oPDF.end_template
...
oPDF.begin_page page_width, page_height
' Template verwenden
oPDF.place_image lTemplate, 0.0, 0.0, 1.0
...weitere Zeichenoperationen...
oPDF.end_page
...
oPDF.close_image lTemplate
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 4.6, »Rasterbildfunktionen«, Seite 109, außer place_
image( ) und 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) werden dürfen.
> Die Funktionen in Abschnitt 4.8, »Hypertextfunktionen«, Seite 118. Hypertextelemente müssen immer auf der Seite definiert werden, auf der sie im Dokument erscheinen sollen. Sie können nicht als Bestandteil eines Templates generiert werden.
Hinweis Auf Templates können Sie zudem alle Bildbearbeitungsalgorithmen anwenden, die in Abschnitt 3.4.2, »Häufig benötigte Codefragmente für Rasterbilder«, Seite 74, beschrieben werden. Setzen Sie dabei für get_value ("imagewidth", image) einfach die Breite des Templates ein
und verfahren Sie ebenso für die Höhe.
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. So
lässt sich zum Beispiel in Acrobat 4 das TouchUp-Textwerkzeug nicht zur Manipulation
von Templates verwenden (dieser Fehler ist in Acrobat 5 behoben). Der PDF-Editor
PitStop 5 ist zwar in der Lage, Templates zu verschieben, kann aber nicht auf einzelne
45
Elemente innerhalb eines Templates zugreifen. Adobe Illustrator 9 und 10 dagegen bieten vollständige Template-Unterstützung.
3.3 Textbehandlung
3.3.1 Die PDF-Standardschriften
PDF-Viewer unterstützen standardmäßig 14 Schriften, die nicht in PDF-Dateien eingebettet zu werden brauchen. Auch wenn eine Schrift nicht in die PDF-Datei eingebettet
wurde, müssen PDF und somit auch PDFlib die Breite der einzelnen Zeichen kennen.
Aus diesem Grund enthält die PDFlib-Binärversion Metrikdaten für die Standardschriften. Die integrierten Metrikdaten sind aber nur für den Zeichensatz host verfügbar (siehe unten). Wird ein anderer Zeichensatz verwendet, sind Metrikdateien erforderlich.
Aus diesem Grund enthält die PDFlib-Distribution Metrikdateien für die PDF-Standardschriften. 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
3.3.2 In PDFlib integrierte 8-Bit-Zeichensätze
PDF unterstützt beliebige Zeichensätze (die Abbildung von numerischen Codes auf die
Zeichen) für 8-Bit-Textschriften, und ebenso ist PDFlib in der Lage, verschiedene Zeichensätze für Text zu unterstützen. Alle von PDFlib intern unterstützten Zeichensätze
werden dabei über symbolische Namen referenziert. Tabelle 3.3 zeigt die symbolischen
Namen für die von PDFlib intern unterstützten Zeichensätze. Außerdem können Zeichensätze in externen Encoding-Dateien verfügbar sein, die mit PDFlib ausgeliefert (siehe unten) oder vom Benutzer definiert werden (siehe Abschnitt 3.3.3, »Benutzerdefinierte 8-Bit-Zeichensätze und Codepages«, Seite 48). Alle unterstützten Zeichensätze lassen
sich in einem Dokument beliebig kombinieren. Im Prinzip können sogar verschiedene
Zeichensätze für eine einzige Schrift verwendet werden, was jedoch nur selten von Interesse sein dürfte.
Hinweis Für eine bestimmte Schrift können nicht unbedingt alle Zeichensätze verwendet werden. Der
Benutzer muss deshalb sicherstellen, dass die Schrift alle Zeichen enthält, die vom jeweiligen
Zeichensatz benötigt werden. Dieses Problem kann auch bei den Acrobat-Standardschriften
auftreten (siehe Tabelle 3.4).
Tabelle 3.3 Von PDFlib intern unterstützte Zeichensätze
46
Zeichensatz
Beschreibung
winansi
Windows-Codepage 1252, eine Obermenge von ISO 8859-1
macroman
Mac-Roman-Encoding, das heißt der Macintosh-Standardzeichensatz
ebcdic
EBCDIC-Codepage 1047; wird z.B. auf den Systemen IBM AS/400 und S/390 verwendet
builtin
Original-Zeichensatz für Symbolschriften oder nicht lateinische Textschriften
host
macroman auf dem Mac, ebcdic auf EBCDIC-basierten Systemen und winansi auf allen anderen
Der winansi-Zeichensatz. Dieser Zeichensatz stellt den Windows-ANSI-Zeichensatz
dar, genauer gesagt Codepage 1252 einschließlich der drei Zeichen, die Microsoft für
Windows 98/2000/XP hinzugefügt hat (Euro, Zcaron und zcaron). Der Zeichensatz
winansi stellt eine Obermenge von ISO 8859-1 (Latin-1) dar und kann somit auch auf
Unix-Systemen verwendet werden.
Hinweis Die meisten PostScript-Schriften enthalten die drei zusätzlichen Zeichen noch nicht. In den
Standardschriften von Acrobat 4 und 5 sind sie aber enthalten.
Der macroman-Zeichensatz. Dieser Zeichensatz zeigt den Mac-OS-Zeichensatz mit folgenden Abweichungen: An Position 219 befindet sich das alte Währungssysmbol und
nicht das Eurozeichen, wie es von Apple neu definiert wurde (diese Inkompatibilität ist
durch die PDF-Spezifikation bedingt). Außerdem sind weder das Apple-Zeichen noch die
mathematischen Symbole vorhanden, die im Mac-OS-Zeichensatz definiert sind.
Der ebcdic-Zeichensatz. Dieser Zeichensatz stellt EBCDIC (Extended Binary Coded
Decimal Interchange Code) dar, der von IBM definiert wurde und auf Mainframe-Systemen wie IBM AS/400 oder S/390 im Einsatz ist. Genauer gesagt verwendet der Zeichensatz ebcdic von PDFlib die EBCDIC-Codepage 1047. Wie auch bei den anderen PDFlib-Zeichensätzen steht ebcdic immer zur Verfügung, nicht nur auf EBCDIC-basierten
Systemen. Der Unterschied besteht jedoch darin, dass die integrierten Metrikdaten für
die Standardschriften auf solchen Systemen nach dem ebcdic-Zeichensatz angeordnet
sind und sich der Zeichensatz host (siehe unten) auch auf den ebcdic-Zeichensatz bezieht.
Der builtin-Zeichensatz. Der Name builtin bezieht sich nicht auf eine bestimmte Anordnung der Zeichen, sondern bedeutet eigentlich einfach »nimm die Schrift wie sie ist
und ändere den Zeichensatz nicht«. Dieses Konzept wird auch als schriftspezifischer
(font specific) Zeichensatz bezeichnet und spielt bei Logo- und Symbolschriften oder
nicht lateinischen Schriften (wie Griechisch oder Kyrillisch) eine entscheidende Rolle.
Solche Schriften 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 Symbolschriften verwendet werden, zum Beispiel für die
Schriften Symbol oder ZapfDingbats. Ob es sich um eine solche Schrift handelt, lässt
sich aus folgendem Eintrag in der AFM-Datei ermitteln:
EncodingScheme FontSpecific
Textschriften können umkodiert (das heißt an eine bestimmte Codepage oder einen bestimmten Zeichensatz angepasst) werden. Mit Symbolschriften ist dies nicht möglich,
so dass dort der Zeichensatz builtin verwendet werden muss.
Hinweis Leider hat sich das Konzept der schriftspezifischen Zeichensätze bei Schriftentwicklern und
Schriftherstellern nicht vollständig durchgesetzt (dies mag an mangelhaften Entwicklungstools liegen). So findet man viele lateinische Textschriften mit vorgeblich schriftspezifischem
Zeichensatz und zahlreiche Symbolschriften, die fälschlicherweise als Textschriften gekennzeichnet sind.
Der host-Zeichensatz. Wie bei builtin spielt auch der Zeichensatz host eine Sonderrolle,
da es sich um keinen bestimmten Zeichensatz handelt. Der Zeichensatz host wird auf
dem Mac auf macroman, auf EBCDIC-basierten Systemen auf ebcdic und auf allen ande-
3.3 Textbehandlung
47
ren System auf winansi abgebildet. Er eignet sich damit in erster Linie zur Entwicklung
plattform unabhängiger Testprogramme (zum Beispiel derjenigen in der PDFlib-Distribution) oder anderen vom Zeichensatz her einfachen Anwendungen. Wenn PDFlibClientprogramme stets den nativen Zeichensatz des Systems (host) verwenden, erzeugen sie auch immer PDF-Text mit »korrektem« Zeichensatz. Im Gegensatz zu allen anderen Aspekten von PDFlib ist der Zeichensatz host an sich nicht portierbar. Aus diesem
Grund empfiehlt er sich auch nicht für den produktiven Betrieb, und sollte dort durch
winansi oder eine andere geeignete Kodierung ersetzt werden.
3.3.3 Benutzerdefinierte 8-Bit-Zeichensätze und Codepages
Um weitere Flexibilität in der Schriftbehandlung zu ermöglichen, unterstützt PDFlib
neben den vordefinierten Zeichensätzen (siehe Abschnitt 3.3.2, »In PDFlib integrierte 8Bit-Zeichensätze«, Seite 46) 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 Zeichensatztabellen mit PostScript-Glyphennamen akzeptiert PDFlib Unicodebasierte Codepage-Tabellen. Auf diese Zeichen kann mit 8-Bit-Codes zugegriffen werden.
Folgende Schritte sind erforderlich, um einen benutzerdefinierten Zeichensatz in einem PDFlib-Programm zu verwenden:
> Generieren Sie eine Beschreibung des Zeichensatzes in einer einfachen Textdatei.
> Konfigurieren Sie den Zeichensatz in der PDFlib-Ressourcedatei (siehe Abschnitt
3.3.7, »Ressourcekonfiguration und die UPR-Ressourcedatei«, Seite 57) oder über set_
parameter( ).
> Stellen Sie eine Schrift bereit (Metrik- und ggf. Fontdatei), die alle im Zeichensatz verwendeten Zeichen enthält. Natürlich müssen die Zeichen in der Schrift entsprechend der Zeichensatztabelle die korrekten PostScript-Glyphennamen tragen.
In der Encoding-Datei werden einfach zeilenweise alle Glyphennamen und die dazugehörigen Nummern aufgelistet. Der folgende Ausschnitt zeigt zum Beispiel die Definition des Zeichensatzes ISO 8859-2 (Latin 2):
% Encoding-Definition für PDFlib
% ISO 8859-2 (Latin-2)
space
32
% 0x20
exclam
33
% 0x21
quotedbl
34
% 0x22
...weitere Glyphenzuordnungen...
yacute
253
% 0xFD
tcommaaccent
254
% 0xFE
dotaccent
255
% 0xFF
Das nächste Beispiel zeigt einen Ausschnitt aus einer Unicode-Codepage für denselben
Zeichensatz ISO 8859-2:
% Codepage-Definition for PDFlib
% ISO 8859-2 (Latin-2)
0x0020
32
% 0x20
0x0021
33
% 0x21
0x0022
34
% 0x22
...weitere Glyphenzuordnungen...
0x00FD
253
% 0xFD
48
0x0163
0x02D9
254
255
% 0xFE
% 0xFF
Formal ausgedrückt ist der Inhalt einer Zeichensatz- oder Codepage-Datei nach folgendem Muster 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 Tabulatorzeichen sowie ein Zeichencode (hexadezimal oder dezimal) zwischen 0 und 255
(dezimal). Dabei sind nur Unicode-Werte der Adobe Glyph List (AGL) zulässig (siehe
Abschnitt 3.3.9, »Unicode-Unterstützung«, Seite 65).
> 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). PDFlib behandelt beide auf dieselbe Art (und kümmert sich nicht um Dateinamen) und
konvertiert automatisch zwischen Zeichensatz- und Codepage-Dateien, sobald dies erforderlich ist. Diese Konvertierung basiert auf Adobes Standardliste der PostScript-Glyphennamen (der Adobe Glyph List oder AGL1). Die AGL ist in PDFlib integriert und enthält mehr als 1000 Glyphennamen. Encoding-Dateien sind bei PostScript-Schriften mit
Glyphennamen erforderlich, die nicht dem Standard entsprechen, während Codepages
sich besser für den Umgang mit TrueType-Schriften eignen, die auf Unicode basieren.
Die Beziehung zwischen dem Namen der Encoding-Datei und dem Namen des eigentlichen Zeichensatzes (der mit findfont( ) zu verwenden ist) wird in der PDFlib-Ressourcedatei oder über set_parameter( ) festgelegt (siehe Abschnitt 3.3.7, »Ressourcekonfiguration und die UPR-Ressourcedatei«, Seite 57).
Mitgelieferte Encoding-Dateien. Die PDFlib-Distribution enthält mehrere Encodingund Codepage-Dateien, die unter Umständen nützlich sind, wenn Sie einen dieser Zeichensätze direkt verwenden oder ihn als Ausgangspunkt für eigene Encoding-Dateien
verwenden möchten. Dazu müssen die PDFlib-Ressourcekonfigurationsdatei sowie die
Fontmetrikdateien verfügbar sein (siehe Abschnitt 3.3.7, »Ressourcekonfiguration und
die UPR-Ressourcedatei«, Seite 57).
Tabelle 3.4 zeigt eine Übersicht der mit PDFlib ausgelieferten Codepages und ihren
Einsatz mit wichtigen Kategorien von Schriften. So enthalten die Acrobat-Standardschriften im Gegensatz zu den Schriftklassen PostScript 3, OpenType Pro und TrueType
»Big Fonts« zum Beispiel nicht alle Zeichen, die für ISO 8859-2 oder ISO 8859-5 benötigt
werden.
Ermittlung von PostScript-Zeichennamen. Um einen eigenen Zeichensatz zu schreiben
oder die richtigen Schriften für einen mitgelieferten Zeichensatz zu finden, benötigen
Sie eine exakte Definition des von einem Zeichensatz benötigten Zeichenvorrats sowie
die genauen Glyphennamen, die in der Fontdatei verwendet werden. Sie müssen also sicherstellen, dass die gewählte Schrift alle vom Zeichensatz benötigten Zeichen enthält.
1. Die AGL kann unter http://partners.adobe.com/asn/developer/type/glyphlist.txt abgerufen werden.
3.3 Textbehandlung
49
Tabelle 3.4 Mit PDFlib ausgelieferte Zeichensätze und ihr Einsatz mit verschiedenen Schriftkategorien
Codepage
Unterstützte Sprachen
PS Level 1/2,
Acrobat 4/51
PostScript 32
OpenType
Pro Fonts3
»Big Fonts«,
z.B. Tahoma
iso8859-1
(Latin-1)
Westeuropäische Sprachen
ja
ja
ja
ja
iso8859-2
(Latin-2)
Slawische Sprachen in Mitteleuropa nein
ja
ja
ja4
iso8859-3
(Latin-3)
Esperanto und Maltesisch
nein
nein
ja
ja
iso8859-4
(Latin-4)
Estnisch, die baltischen Sprachen
und Grönländisch
nein
nein
ja
ja
iso8859-5
Bulgarisch, Russisch und Serbisch4
nein
nein
ja
ja
iso8859-6
Arabisch
nein
nein
nein
ja
iso8859-7
Modernes Griechisch
nein
nein
2 Zeichen
fehlen
ja
iso8859-8
Hebräisch und Jüdisch4
nein
nein
nein
ja
iso8859-9
(Latin-5)
Westeuropäisch und Türkisch
5 Zeichen
fehlen
ja
ja
ja5
iso8859-10
(Latin-6)
Nordische Sprachen (Variation von
Latin-4)
nein
nein
1 Zeichen
fehlt
ja
iso8859-13
(Latin-7)
Baltische Sprachen
nein
ja
ja
ja
iso8859-14
(Latin-8)
Keltisch6
nein
nein
nein
nein
iso8859-15
(Latin-9)
Ergänzt Latin-1 um das Eurozeichen
und einige französische und
finnische Zeichen
ja7
ja
ja
ja
iso8859-16
(Latin-10)
Ungarisch, Polnisch, Rumänisch und nein
Slowenisch
ja
ja
ja
cp1250
Mitteleuropäisch
ja
ja
ja
4
nein
cp1251
Kyrillisch
nein
nein
ja
ja
cp1252
Westeuropäisch
ja
ja
ja
ja
cp1253
Griechisch
nein
nein
2 Zeichen
fehlen
ja
cp1254
Türkisch
5 Zeichen
fehlen
ja
ja
ja5
cp1255
Hebräisch4
nein
nein
nein
ja
cp1256
Arabisch
nein
nein
nein
5 Zeichen
fehlen
cp1257
Baltisch
nein
ja
ja
ja
cp1258
Vietnamesisch
nein
nein
nein
ja
1. Ursprünglicher Adobe Latin Zeichensatz (Type-1-Schriften seit 1982)
2. Erweiterter Adobe Latin Zeichensatz (CE-Fonts) (Type 1 Schriften seit PostScript 3)
3. Entspricht im Wesentlichen der Adobe Glyph List (AGL).
4. Funktioniert in Acrobat 4 nicht richtig. Dieser Fehler wurde in Acrobat 5 behoben.
5. Acrobat 4 zeigt das Zeichen »Großes I mit Punkt« (221 = 0xDD) im Gegensatz zu Acrobat 5 nicht korrekt an.
6. 14 Zeichen funktionieren in Acrobat 4/5 nicht, da sie nicht in der Adobe Glyph List (AGL) liegen.
7. Bis auf das Eurozeichen in PostScript Level 1 und 2.
50
Die mit Acrobat 4/5 mitgelieferten 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 Zeichensatzangelegenheiten 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
Zur Erleichterung für den PDFlib-Benutzer wird das PostScript-Programm print_
glyphs.ps mit PDFlib ausgeliefert, das die Namen aller in einer PostScript-Schrift vorhandenen Zeichen 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, distillieren sie oder betrachten sie mit einem Level-2-kompatiblen PostScript-Viewer. Das Programm druckt alle in der Schrift
vorhandenen Zeichen, und zwar alphabetisch nach Glyphennamen sortiert.
Ist ein von einem benutzerdefinierten Zeichensatz benötigtes Zeichen in einer
Schrift nicht vorhanden, so fehlt es auch im PDF-Dokument.
3.3.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 Eurozeichen enthält, und überprüfen, an welcher Position es sich befindet. Einige Beispiele:
> Im Zeichensatz winansi befindet es sich an Position 0x80 (hexadezimal) oder 128 (dezimal).
> Die Zeichensätze macroman und iso8859-1 enthalten kein Eurozeichen.
> Der Zeichensatz iso8859-15 stellt eine Erweiterung von iso8859-1 dar, in der das Eurozeichen an Position 0xA4 (hexadezimal) oder 164 (dezimal) ergänzt wurde.
Danach müssen Sie eine Schrift aussuchen, die das Eurozeichen enthält. Dies ist bei vielen, aber durchaus nicht allen modernen Schriften der Fall. Auch hier einige Beispiele:
> Die Standardschriften von Acrobat enthalten das Eurozeichen erst ab Version 4.05.
In älteren Versionen ist es nicht vorhanden.
> 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
Symbol-Font verwenden, der sich dort an Position 0xA0 (hexadezimal) oder 160 (dezimal) befindet. Er ist in der Version des Symbol-Font, die ab Acrobat Version 4.0 ausgeliefert wird, sowie im in PostScript-3-Geräte eingebauten Symbol-Font verfügbar.
Wenn Sie die Schrift nicht einbetten, zeigt Acrobat den Text mit einer seiner Ersatzschriften an. Diese enthalten das Eurozeichen erst ab Acrobat Version 4.0. Das kann zu
uneinheitlichen Ergebnissen bei Anzeige und Ausdruck führen.
1. Siehe http://www.fontlab.com
2. Informationen über die in PostScript-Schriften verwendeten Glyphennamen finden Sie unter http://partners.adobe.com/
asn/developer/typeforum/unicodegn.html (Schriftanbieter müssen sich aber nicht an diese Empfehlungen für Glyphennamen halten).
3.3 Textbehandlung
51
0
1
0 1 2 3 4 5 6
7 8 9 A B C D E F
000
001
002
003
004
005
006
007
010
011
012
013
014
015
016
017
020
021
022
023
024
025
026
027
030
031
032
033
034
035
036
037
H I J K L M N O
2
! " # $ % & ( ) * + , - . /
3 0 1 2 3 4 5 6 7 8 9 : ; < = > ?
040
041
042
043
044
045
046
047
050
051
052
053
054
055
056
057
060
061
062
063
064
065
066
067
070
071
072
073
074
075
076
077
4 @ A B C D E F G H I J K L M N O
5 P Q R S T U V W X Y Z [ \ ] ^ _
100
101
102
103
104
105
106
107
110
111
112
113
114
115
116
117
120
121
122
123
124
125
126
127
130
131
132
133
134
135
136
137
6 a b c d e f g h i j k l m n o
140
141
142
143
144
145
146
147
150
151
152
153
154
155
156
157
7 p q r s t u v w x y z { | } ~
160
161
162
163
164
165
166
167
170
171
172
173
174
175
176
177
8 9 A
B
C
D
E
F
200
201
202
203
204
205
206
207
210
211
212
213
214
215
216
217
220
221
222
223
224
225
226
227
230
231
232
233
234
235
236
237
`

¬
¼
Ì
'

½
Í

®
¾
Î

¯
¿
Ï

¡ ¢
° ± ²
À Á Â
Ð Ñ Ò

¥
µ
Å
Õ

¦
¶
Æ
Ö

§
·
Ç
×

¨
¸
È
Ø

£
³
Ã
Ó
240
241
242
243
244
245
246
247
250
251
252
253
254
255
260
261
262
263
264
265
266
267
270
271
272
273
274
300
301
302
303
304
305
306
307
310
311
312
313
320
321
322
323
324
325
326
327
330
331
332
340
341
342
343
344
345
346
347
350
351
360
361
362
363
364
365
366
367
370
371

¤
´
Ä
Ô

ª
º
Ê
Ú

«
»
Ë
Û
256
257
275
276
277
314
315
316
317
333
334
335
336
337
352
353
354
355
356
357
372
373
374
375
376
377

©
¹
É
Ù
Abb. 3.1 Der Zeichensatz PDFDocEncoding mit hexadezimalen und oktalen Codes, so wie
er in PDF 1.3 definiert ist. Dieser kann nicht für Seitenbeschreibungen verwendet werden!
3.3.5 Zeichensätze für Hypertext
PDF unterstützt zwei Methoden zur Kodierung von Hypertextelementen wie Lesezeichen, Anmerkungen und Dokumentinfofeldern (Dokumentzusammenfassung). Bis
Acrobat 3 mussten alle Hypertextstrings mit einem speziellen 8-Bit-Zeichensatz namens PDFDocEncoding kodiert werden (PDFDocEncoding kann nicht für Text in Seitenbeschreibungen verwendet werden). Ab Acrobat 4 können in allen Hypertextelementen
Unicode-Strings benutzt werden. Weitere Informationen über Unicode finden Sie in Abschnitt 3.3.9, »Unicode-Unterstützung«, Seite 65.
PDFDocEncoding (siehe Abbildung 3.1) stellt eine Obermenge von ISO 8859-1 (Latin 1)
dar und enthält deshalb alle ASCII-Zeichen im unteren Bereich. PDFDocEncoding und
die Windows-Codepage 1252 sind recht ähnlich, weichen aber im Bereich zwischen 128
und 160(&H80 und &HA0) stark voneinander ab.
Viele Clients können ohne zusätzliche Maßnahmen unmittelbar mit PDFDocEncoding arbeiten. Da sich der Mac-Zeichensatz aber gravierend von PDFDocEncoding unterscheidet, müssen Mac-Strings gesondert konvertiert werden, wenn sie in Hypertextelementen vorkommen und nicht-ASCII-Zeichen enthalten. Mac-Sonderzeichen müssen in
52
Unicode umgewandelt werden, bevor sie in Hypertextelementen einsetzbar sind. Diese
Umwandlung muss vom Client durchgeführt werden.
3.3.6 PostScript-, TrueType- und OpenType-Schriften
Schrifteinbettung in PDF. PDF unterstützt Schriften jenseits der 14 Standardschriften
auf verschiedene Art und Weise. PDFlib kann Fonts in die generierte PDF-Ausgabe einbetten. Alternativ dazu kann ein Fontdeskriptor eingebettet werden, der nur die Metrik
der Zeichen (ohne die eigentlichen Zeichenbeschreibungen) sowie allgemeine Schriftinformationen 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 im PDF-Dokument enthaltenen Fontdeskriptors eine Ersatzschrift konstruiert. Tabelle 3.5 zeigt die verschiedenen Situationen bei der Schriftverwendung und
die jeweils erforderlichen Font- und Metrikdateien.
Wird eine Schrift mit fontspezifischem Zeichensatz verwendet (Symbolschrift), aber
nicht in die PDF-Ausgabe eingebettet, ist das PDF-Dokument unbrauchbar, sofern die
fragliche Schrift nicht bereits auf dem Zielsystem installiert ist (denn Acrobat kann nur
lateinische Textschriften simulieren). Solche PDF-Dokumente sind von Natur aus nicht
portierbar, wenngleich sie in beschränktem Rahmen wie zum Beispiel beim innerbetrieblichen Dokumentenaustausch sinnvoll sein können.
Tabelle 3.5 Schrifteinsatz mit erforderlichen Metrik- und Fontdateien
Schrifteinsatz
Metrikdatei erforderlich?
Fontdatei erforderlich?
Eine der 14 Standardschriften mit host-Encoding1,2
nein
nein3
Eine der 14 Standardschriften mit anderem Zeichensatz
als host2
ja (AFM-Dateien in PDFlibDistribution enthalten)
nein
TrueType- oder OpenType-Schrift, die auf dem Mac- oder
Windowsystem installiert ist (Systemschriften)
nein
nein
PostScript-Nichtstandardschriften ohne Einbettung
ja
nein
PostScript-Nichtstandardschriften mit Einbettung
ja
ja
Weitere Schrift/Zeichensatz-Kombinationen, für die die
Metriken in PDFlib vorhanden sind (siehe unten)
nein
ja, wenn Einbettung
erwünscht
TrueType-Schriften mit oder ohne Einbettung
nein
ja
OpenType-Schriften mit TT- oder PS-Zeichenbeschreibungen
nein
ja
Standard-CID-Schriften4
nein
nein
Nicht-Standard-CID-Schriften
(nicht unterstützt)
(nicht unterstützt)
1. Eine Liste der Standardschriften finden Sie in Abschnitt 3.3.1, »Die PDF-Standardschriften«, Seite 46.
2. Eine Definition des PDFlib-Systemzeichensatzes finden Sie in Abschnitt 3.3.2, »In PDFlib integrierte 8-Bit-Zeichensätze«, Seite 46.
3. Zeichenbeschreibungen können im PostScript-, aber nicht im TrueType-Format zur Einbettung bereitgestellt werden.
4. Weitere Informationen über CID-Fonts finden Sie in Abschnitt 3.3.8, »Japanischer, chinesischer und koreanischer Text«, Seite 60.
OpenType-Schriften. OpenType ist ein neues Fontformat, das PostScript und TrueType
kombiniert und ein plattformunabhängiges Dateiformat nutzt. Windows 2000, Windows XP und Mac OS X verfügen über integrierte OpenType-Unterstützung. Es gibt zwei
Varianten von OpenType-Schriften:
> OpenType-Schriften mit TrueType-Zeichenbeschreibungen (*.ttf) entsprechen weitgehend den herkömmlichen TrueType-Schriften.
3.3 Textbehandlung
53
> OpenType-Schriften mit PostScript-Zeichenbeschreibungen (*.otf) enthalten PostScript-Daten in einem TrueType-Dateiformat. Diese Variante wird auch CFF genannt.
PDFlib unterstützt beide Varianten von OpenType-Schriften. Die Informationen in den
folgenden Abschnitten zur Konfiguration von PostScript- und TrueType-Schriften beziehen sich auch auf OpenType-Schriften.
PostScript-Type-1-Schriften. 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-spezifische Format PFM (Printer Font Metrics) für Fontmetrikdaten. Da PFM-Dateien keine
vollständigen Metrikinformationen enthalten, sondern nur die unter Windows verwendeten Glyphen (Codepage 1252), können sie nur mit den Zeichensätzen winansi
oder builtin eingesetzt werden, während sich auf AFM basierende Fontmetriken in jeden von der Schrift unterstützten Zeichensatz umsortieren lassen.
> Das plattformunabhängige Format PFA (Printer Font ASCII) und das Windows-spezifische Format PFB (Printer Font Binary) für Zeichenbeschreibungen im PostScript-Type1-Format (manchmal auch »ATM-Schriften« genannt). PostScript-Type-3-Schriften
werden nicht unterstützt.
> Auf dem Mac werden auch die Mac-typischen ressourcenbasierten PostScript-Type1-Schriften, manchmal LWFN-Schriften (LaserWriter Font) genannt, unterstützt.
> OpenType-Schriften mit PostScript-Zeichenbeschreibungen (*.otf).
Wenn Sie zu einer PostScript-Schrift die Zeichenbeschreibungs-, aber nicht die Metrikdatei besitzen, können Sie versuchen, die fehlenden Metrikdaten mit einem der frei verfügbaren Hilfsprogramme zu generieren. Das Softwarepaket T1lib beispielsweise1 enthält das Programm type1afm zur Erzeugung von AFM-Metriken aus PFA- oder PFBZeichenbeschreibungsdateien.
PostScript-Schriftnamen. Um eine Schrift in PDFlib nutzen zu können, müssen Sie den
richtigen PostScript-Schriftnamen (unter Berücksichtigung von Groß- und Kleinschreibung) verwenden. Es gibt mehrere Möglichkeiten, den korrekten Namen für eine PostScript-Schrift 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 verwenden Sie den Rest als Schriftnamen.
> Ist ATM (Adobe Type Manager) installiert, können Sie auf die Zeichenbeschreibungsdatei (*.pfb) oder auf die Metrikdatei (*.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-Schriftname kann ganz anders lauten als der Fontname in Windows. So erscheint die Schrift »AvantGarde-Demi« (PostScript-Name) im Windows-Schriftmenü zum Beispiel als »AvantGarde, Bold«. Genauso ist der Schriftname, der in den .inf-Dateien für Windows
erscheint, für den Einsatz mit PDF nicht relevant.
Performance bei PostScript-Schriften. Es ist wichtig sich klarzumachen, inwieweit die
Schriftbehandlung die Performance von PDFlib beeinflusst. Im Allgemeinen wird auf
1. Siehe http://www.neuroinformatik.ruhr-uni-bochum.de/ini/PEOPLE/rmz/t1lib/t1lib.html
54
die Metrikdaten einer Schrift (im Arbeitsspeicher oder auf der Festplatte) zugegriffen,
wenn eine bestimmte Kombination von Schrift und Zeichensatz zum ersten Mal verwendet wird. Alle weiteren Zugriffe auf dieselbe Kombination erfolgen über den internen Fontcache von PDFlib, was keine Leistungseinbußen zur Folge hat. Bezüglich der
Performance bei der Schriftbehandlung ist folgendes anzumerken:
> PFM-Metrikdateien können wegen der geringen Größe und des Binärformats viel
schneller gelesen werden als auf Text basierende AFM-Metrikdateien. Sie sind aber
nicht für alle Zeichensätze einsetzbar.
> AFM-Dateien enthalten viele nützliche Informationen über zahlreiche Aspekte des
Schriftgebrauchs und können außerdem für beliebige Zeichensätze verwendet werden. Obwohl für PDFlib nur die bloßen Laufweiten erforderlich sind, muss die AFMDatei vollständig geparst werden.
TrueType- und OpenType-Schriften. PDFlib unterstützt auf allen Systemen TrueTypeund OpenType-Schriften. Die TrueType-Fontdatei muss im TTF-Format von Windows
bereitgestellt werden. Alternativ dazu können die Schriften auf dem Mac und unter
Windows im System installiert sein. Im Gegensatz zu PostScript-Type-1-Schriften erfordern TrueType- und OpenType-Schriften keine zusätzliche Metrikdatei, da die Metrikdaten aus der Fontdatei selbst extrahiert werden. PDFlib unterstützt gegenwärtig folgende Varianten von TrueType-Schriften:
> Unicode-kompatible TrueType-Schriften (cmap-Tabelle mit Plattformkennung 3, Zeichensatzkennung 1). Die meisten modernen TrueType-Schriften für Windows fallen
in diese Kategorie und können mit dem PDFlib-Zeichensatz winansi verwendet werden. Andere Unicode-kompatible Schriften können mit einem beliebigen PDFlib-Zeichensatz benutzt werden, solange die Schrift auch tatsächlich alle vom Zeichensatz
definierten Zeichen enthält. Mit der unten beschriebenen Software »font properties
extension« können Sie überprüfen, welche Codepages von einer bestimmten Schrift
unterstützt werden.
> Symbol-Schriften mit einem benutzerdefinierten Zeichensatz (cmap-Tabelle mit
Plattformkennung 3, Zeichensatzkennung 0). Für solche Schriften muss der PDFlibZeichensatz builtin gewählt werden.
> Mac-TrueType-Schriften sowie die meisten TrueType-Schriften für Windows sind
auch mit dem PDFlib-Zeichensatz macroman einsetzbar, da sie neben den WindowsInformationen auch die notwendigen Mac-Daten enthalten (cmap-Tabelle mit Plattformkennung 1, Zeichensatzkennung 0).
Die oben erwähnte Unterscheidung zwischen Text- und Symbolschriften scheint offensichtlich zu sein, in der Praxis ist es manchmal aber gar nicht einfach, die Kategorie einer Schrift festzustellen. Aus diversen Gründen können Textschriften zum Beispiel als
TrueType-Symbolschriften kodiert sein und umgekehrt. Im Falle eines unpassenden
Zeichensatzes unterstützt Sie PDFlib, indem sie innerhalb der PDFlib-Exception eine
Meldung mit Vorschlägen für andere Zeichensätze anzeigt.
Hinweis PDFlib unterstützt keine TrueType-Collections (*.ttc).
Betriebssystemschriften. Neben dem Zugriff auf Fontdateien, die in PDFlib manuell
konfiguriert sind (siehe Abschnitt 3.3.7, »Ressourcekonfiguration und die UPR-Ressourcedatei«, Seite 57) können TrueType- und OpenType-Schriften auch direkt vom Betriebssystem bezogen werden. Solche Schriften bezeichnen wir als Betriebssystemschriften. Statt sich mit Font- und Konfigurationsdateien herumzuschlagen, installieren Sie
3.3 Textbehandlung
55
die Schrift einfach im Betriebssystem (das heißt, Sie legen sie einfach im Verzeichnis
fonts ab) und schon kann sie von PDFlib verwendet werden. Im Betriebssystem installierte Schriften werden nicht zur Einbettung von Standardschriften verwendet. Die Unterstützung von Betriebssystemschriften ist auf dem Mac und unter Windows verfügbar:
> Unter Windows werden Betriebssystemschriften für TrueType- und OpenTypeSchriften (TT- und PS-Variante) unterstützt.
> Auf Mac OS 9 und Mac OS X werden Betriebssystemschriften für TrueType-Schriften
(Suitcases), flache TrueType-Schriften im Windows-Stil, Datafork-TrueType-Schriften (.dfont) sowie OpenType-Schriften (TT- und PS-Variante) unterstützt. Ältere MacSchriften funktionieren nur mit dem macroman-Zeichensatz, während neuere
Schriften oft auch andere Zeichensätze unterstützen.
TrueType-Schriftnamen. Wird eine Schrift in PDFlib benutzt, so muss dies immer mit
dem genauen TrueType-Schriftnamen (unter Berücksichtigung von Groß- und Kleinschreibung) erfolgen. Dieser entspricht dem Namen, der in der Benutzerschnittstelle erscheint. Um diesen Namen in Windows herauszufinden, doppelklicken Sie einfach auf
die TrueType-Fontdatei. Verwenden Sie den Namen in der ersten Zeile des angezeigten
Fensters mit Schriftinformationen (natürlich ohne einen der Begriffe TrueType oder
OpenType in Klammern). Benutzen Sie nicht den Namen in der zweiten Zeile nach
Schriftart! Auch können Schriftnamen 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 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.
Der Name einer TrueType-Schrift im generierten PDF-Dokument kann von den in
PDFlib (oder Windows) benutzten Namen abweichen. Das ist normal und liegt darin begründet, dass PDF den PostScript-Namen einer TrueType-Schrift verwendet, der aber
nicht unbedingt mit dem ursprünglichen TrueType-Namen übereinstimmt (zum Beispiel TimesNewRomanPSMT bzw. Times New Roman).
Wenn Sie sich intensiver mit TrueType-Schriften beschäftigen möchten, dann können Sie sich die von Microsoft kostenlos erhältliche Software »font properties extension«1 besorgen, die zahlreiche Einträge der TrueType-Tabellen einer Schrift in lesbarer
Form anzeigt.
Hinweis Im Gegensatz zu PostScript-Schriften dürfen die Namen von TrueType- und OpenType-Schriften
Leerzeichen enthalten.
Rechtliche Aspekte der Schrifteinbettung. Es ist wichtig anzumerken, dass der bloße
Besitz einer Fontdatei nicht unbedingt dazu berechtigt, die Schrift in ein PDF-Dokument 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 besondere Online- oder Einbettungslizenzen. Schließlich gibt es auch noch die Variante, die Einbettung nur bei Verwendung von Untergruppen zu erlauben. Überprüfen Sie deshalb
bitte die rechtlichen Aspekte, bevor Sie Schriften mit PDFlib einbetten. PDFlib hält sich
1. Siehe http://www.microsoft.com/typography/property/property.htm
56
an Einbettungsbeschränkungen, wenn diese in einer TrueType-Schrift spezifiziert sind.
Dies wird über ein Einbettungsflag bewerkstelligt, das auf no embedding1 gesetzt sein
kann. In diesem Fall kommt PDFlib der Bitte des Herstellers nach und weist jeden Versuch zurück, die Schrift einzubetten.
3.3.7 Ressourcekonfiguration und die UPR-Ressourcedatei
Um die von PDFlib behandelten Schriften und Zeichensätze plattformunabhängig und
benutzerdefinierbar zu machen, kann eine Konfigurationsdatei angegeben werden, in
der die verfügbaren Schriften gemeinsam mit den Namen der Font- und Metrikdateien
sowie weiterer Encoding-Dateien aufgeführt sind. Außerdem kann die Konfiguration
dynamisch zur Laufzeit durch Anfügen von Ressourcen mit set_parameter( ) erfolgen.
Für die Konfigurationsdatei 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 uns jedoch erlaubt, das ursprüngliche UPR-Format für unsere Zwecke zu erweitern. Das von PDFlib verwendete
UPR-Dateiformat wird unten beschrieben.2 Es gibt zudem ein Hilfsprogramm namens
makepsres (das oft mit dem X Window System mitgeliefert wird), das aus PostScriptFont- und -Metrikdateien automatisch UPR-Dateien generiert.
Hinweis Als Alternative zur Konfiguration von Schriften über UPR-Dateien oder set_parameter( ) ist in
manchen Situationen der von PDFlib angebotene Einsatz von Schriften sinnvoll, die im Betriebssystem installiert sind (siehe Abschnitt 3.3.6, »PostScript-, TrueType- und OpenType-Schriften«, Seite 53).
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.
> Generell hebt ein Gegenschrägstrich die Sonderbedeutung des nachfolgenden Zeichens auf. So bewirkt ein Gegenschrägstrich ’\’ am Zeilenende, dass die Zeile auch
nach dem Newline-Zeichen fortgeführt wird. In Windows-Verzeichnisnamen müssen zwei Gegenschrägstriche ’\\’ oder ein einfacher Schrägstrich ’/’ benutzt werden.
> Der Punkt ’ . ’ dient als Abschnittsende und muss mit einem führenden Gegenschrägstrich versehen werden, wenn er am Anfang einer Zeile als normales Zeichen
interpretiert werden soll.
> Es wird prinzipiell zwischen Groß- und Kleinschreibung unterschieden.
> Kommentare beginnen mit dem Prozentzeichen ’%’ und und enden am Zeilenende.
> Leer- und Tabulatorzeichen werden ignoriert.
UPR-Dateien bestehen aus folgenden Komponenten:
> Eine Kopfzeile zur Identifizierung der Datei, die folgendermaßen aussieht:
PS-Resources-1.0
> Ein Abschnitt, der alle Arten von Ressourcekategorien auflistet, die in der Datei beschrieben werden. Jede Zeile beschreibt eine Kategorie. Die Liste wird mit einem
1. Genauer gesagt: wenn das Flag fsType in der OS/2-Tabelle der Schrift den Wert 2 hat.
2. Eine vollständige Spezifikation befindet sich in dem Buch »Programming the Display PostScript System with X« (Appendix A), das unter http://partners.adobe.com/asn/developer/PDFS/TN/DPS.refmanuals.TK.pdf erhältlich ist.
3.3 Textbehandlung
57
Punkt abgeschlossen. Die verfügbaren Ressourcekategorien werden unten beschrieben. Dieser Abschnitt ist nur aus Kompatiblitätsgründen vorhanden und wird von
PDFlib ignoriert.
Hinweis Das Pfadpräfix in der UPR-Datei wird nicht von allen PDFlib-Editionen unterstützt. So ist es zum
Beispiel bei der PDFlib-ActiveX-Komponente wirkungslos, da diese stattdessen Einträge aus der
Windows-Registrierung verwendet und standardmäßig alle Dateien im PDFlib-Verzeichnis
fonts erwartet. Wenn Sie auf Ressourcen in anderen Verzeichnissen zugreifen möchten, müssen
Sie mit doppelten Gleichheitszeichen arbeiten (siehe unten).
> Ein Abschnitt für jede der Ressourcekategorien, die am Dateianfang aufgeführt wurden. Jeder Abschnitt beginnt mit einer Zeile für die Ressourcekategorie, gefolgt von
einer beliebigen Anzahl von Zeilen, die die verfügbaren Ressourcen beschreiben. Diese Liste wird durch eine Zeile mit einem einzelnen Punkt abgeschlossen. Jede Ressourcezeile besteht aus dem Namen der Ressource (bei Gleichheitszeichen sind Anführungszeichen erforderlich), einem Gleichheitszeichen sowie dem zugehörenden
relativen oder absoluten Dateinamen für die Ressource. Relative Dateinamen werden als relativ zum PDFlib-Verzeichnis fonts interpretiert. Werden zwei Gleichzeitszeichen verwendet, so gilt der Dateiname als absolut und das Pfadpräfix wird nicht
vorangestellt.
Unterstützte Ressourcekategorien. Tabelle 3.6 führt die von PDFlib unterstützten Ressourcekategorien auf. In der UPR-Datei können zur Kompatibilität mit Display-PostScript-Installationen auch andere Ressourcekategorien vorkommen, diese werden aber
stillschweigend ignoriert.
Tabelle 3.6 In PDFlib unterstützte Ressourcekategorien
Ressourcekategoriename
Erklärung
FontAFM
PostScript-Fontmetrikdatei im AFM-Format
FontPFM
PostScript-Fontmetrikdatei im PFM-Format
FontOutline
PostScript-, TrueType- oder OpenType-Zeichenbeschreibungsdatei
Encoding
Textdatei mit 8-Bit-Zeichensatz oder Codepagetabelle
Vermeiden Sie redundante Ressourceeinträge. Nehmen Sie zum Beispiel eine bestimmte Fontmetrikinformation nur einmal auf. Achten Sie zudem darauf, dass der Schriftname in der UPR-Datei exakt mit dem tatsächlichen Schriftnamen übereinstimmt (auch
wenn PDFlib Abweichungen toleriert).
Auf Mac OS Classic muss der Doppelpunkt ’:’ als Trennzeichen in Verzeichnisangaben verwendet werden. Die Schriftnamen der ressourcenbasierten PostScript-Type-1Schriften (LWFN-Fonts) müssen mit dem vollständigen Pfad einschließlich des VolumeNamens angegeben werden:
Foo-Italic=Classic:Data:Fonts:FooIta
UPR-Beispieldatei. Das folgende Listing zeigt ein Beispiel für eine von PDFlib verwendete UPR-Konfigurationsdatei. Darin werden die Metriken der 14 Standardschriften von
PDF einschließlich der Metrik- und Zeichenbeschreibungsdateien für weitere Schriften
sowie ein benutzerdefinierter Zeichensatz beschrieben:
58
PS-Resources-1.0
FontAFM
FontPFM
FontOutline
Encoding
.
FontAFM
Code-128=Code_128.afm
Courier=Courier.afm
Courier-Bold=Courier-Bold.afm
Courier-BoldOblique=Courier-BoldOblique.afm
Courier-Oblique=Courier-Oblique.afm
Helvetica=Helvetica.afm
Helvetica-Bold=Helvetica-Bold.afm
Helvetica-BoldOblique=Helvetica-BoldOblique.afm
Helvetica-Oblique=Helvetica-Oblique.afm
Symbol=Symbol.afm
Times-Bold=Times-Bold.afm
Times-BoldItalic=Times-BoldItalic.afm
Times-Italic=Times-Italic.afm
Times-Roman=Times-Roman.afm
ZapfDingbats=ZapfDingbats.afm
.
FontPFM
Foobar-Bold=foobb___.pfm
% Beispiel für absoluten Pfadnamen ohne Anfügen des Pfadpräfix
% (zwei Gleichheitszeichen)
Mistral==c:/psfonts/pfm/mist____.pfm
.
FontOutline
Code-128=Code_128.pfa
ArialMT=Arial.ttf
.
Encoding
iso8859-2=iso8859-2.enc
cp1250=cp1250.cpg
.
Suchen der UPR-Ressourcedatei. Sollen nur in PDFlib integrierte Ressourcen verwendet werden (PDF-Standardschriften mit Systemzeichensatz), dann ist keine UPR-Konfigurationsdatei erforderlich, da PDFlib selbst über alle notwendigen Ressourcen verfügt.
Sollen andere Ressourcen verwendet werden, sucht PDFlib an verschiedenen Stellen
nach einer Ressourcedatei. Dieser Vorgang ist konfigurierbar und besteht aus folgenden
Schritten:
> Die PDFlib-ActiveX-Komponente ermittelt mittels eines Registrierungseintrags die
Datei pdflib.upr im Unterverzeichnis fonts des PDFlib-Installationsverzeichnisses.
Kann diese Datei nicht geöffnet werden, wird ein IOError ausgelöst.
> Kann die Ressourcedatei zwar geöffnet, die erforderliche Ressourcekategorie aber
nicht gefunden werden, so wird ein SystemError ausgelöst.
Konfiguration von Ressourcen ohne UPR-Datei. Statt mit einer UPR-Datei zu arbeiten,
können Sie einzelne Ressourcen auch direkt mit der Funktion set_parameter( ) im Quellcode konfigurieren. Diese Funktion erhält einen Kategorienamen sowie den zugehörenden Ressourceeintrag, in etwa so, wie diese auch im entsprechenden Abschnitt in der
UPR-Datei erscheinen, zum Beispiel:
3.3 Textbehandlung
59
oPDF.set_parameter "FontAFM", "Foobar-Bold=foobb___.afm"
oPDF.set_parameter "FontOutline", "Foobar-Bold=foobb___.pfa"
Wie in der UPR-Datei wird ein Dateiname als absolut interpretiert, wenn er nach doppelten Gleichheitszeichen steht. Ist nur ein einziges Gleichheitszeichen vorhanden,
wird das Pfadpräfix verwendet, sofern es konfiguriert ist.
3.3.8 Japanischer, chinesischer und koreanischer Text
CJK-Unterstützung in Acrobat und PDF1. Bereits in Acrobat 3J wurden japanische
Schriften unterstützt. Mit Acrobat 4 wurde die vollständige Unterstützung von japanischen, chinesischen und koreanischen CID-Schriften (Character ID) eingeführt. Das gilt
genauso für die nicht-japanischen Versionen des Acrobat-Vollprodukts und den kostenlos erhältlichen Acrobat Reader. Um CJK-Dokumente in Acrobat zu verwenden, ist einer
der folgenden Schritte erforderlich:
> 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 asiatische Sprachen« (Windows) oder »Language Kit« (Mac). Die erforderlichen Hilfsdateien (Zeichen und Zeichensätze) 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
CJK-Zeichensätze und -Schriften. Von diversen Standardisierungsgremien, Firmen
und anderen Organisationen wurde über die Jahre hinweg ein breites Spektrum an CJKZeichensätzen entwickelt. Zum Glück werden alle der vorherrschenden Zeichensätze
standardmäßig auch von Acrobat und PDF unterstützt. Acrobat 4 unterstützt unterschiedlichste Zeichensätze für CJK-Schriften. Da ein Zeichensatz für CJK-Text wesentlich
komplizierter ist als für lateinischen Text, reicht ein einfacher Zeichensatz mit 256 Einträgen einfach nicht aus. Stattdessen arbeiten PostScript und PDF mit dem Konzept der
character collections und character maps (CMaps) zur Anordnung der Zeichen in einer
Schrift. Vom Konzept her kann man sich CMaps wie sehr große Zeichensätze für CJKSchriften vorstellen.
Acrobat unterstützt einen Satz von Standardschriften für CJK-Text. Diese Schriften
werden mit der Acrobat-Installation ausgeliefert (oder mit den asiatischen Fontpaketen) und müssen somit nicht in der PDF-Datei eingebettet sein (genauso wie die 14 Standardschriften 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 3.7 zeigt die Standardschriften und CMaps. Die Acrobat-4-Schriften können auch mit Acrobat 5 verwendet werden, für Anzeige und Ausdruck werden jedoch die entsprechenden Acrobat-5-Schriften benutzt, falls eine benötigte Schrift nicht
auf dem System installiert ist.
Wie aus Tabelle 3.7 hervorgeht, unterstützen die standardmäßig vorhandenen
CMaps die meisten CJK-Zeichensätze, die auf Mac-, Windows- und Unix-Systemen ver1. Bei dieser Gelegenheit soll das grundlegende Werk »CJKV information processing – Chinese, Japanese, Korean & Vietnamese 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 http://www.adobe.com/products/acrobat/cacrrasianfontpack.html
60
wendet werden, sowie einige andere herstellerspezifische Zeichensätze. Dabei werden
inbesondere die wichtigen japanischen Zeichensätze Shift-JIS, EUC, ISO 2022 und Unicode (UCS-2) unterstützt. Tabellen mit allen unterstützten Zeichen sind bei Adobe1 erhältlich; CMap-Beschreibungen finden sich in Tabelle 3.8.
Tabelle 3.7 Acrobats Standardschriften und CMaps (Zeichensätze) für Japanisch/Chinesisch/Koreanisch
Sprache
Schriftname
Vereinfachtes
Chinesisch
STSong-Light1
Traditionelles
Chinesisch
MHei-Medium1
Beispiel
STSongStd-Light-Acro2
MSung-Light1
Unterstützte CMaps (Zeichensätze)
GB-EUC-H, GB-EUC-V, GBpc-EUC-H, GBpc-EUC-V,
GBK-EUC-H, GBK-EUC-V, GBKp-EUC-H, GBKp-EUC-V,
GBK2K-H, GBK2K-V, UniGB-UCS2-H, UniGB-UCS2-V
B5pc-H, B5pc-V, HKscs-B5-H, HKscs-B5-V, ETen-B5-H,
ETen-B5-V, ETenms-B5-H, ETenms-B5-V, CNS-EUC-H,
CNS-EUC-V, UniCNS-UCS2-H, UniCNS-UCS2-V
MSungStd-Light-Acro2
Japanisch
HeiseiKakuGo-W51
HeiseiMin-W31
KozMinPro-Regular-Acro2
Koreanisch
HYGoThic-Medium1
HYSMyeongJo-Medium1
83pv-RKSJ-H, 90ms-RKSJ-H, 90ms-RKSJ-V, 90mspRKSJ-H, 90msp-RKSJ-V, 90pv-RKSJ-H, Add-RKSJ-H,
Add-RKSJ-V, EUC-H, EUC-V, Ext-RKSJ-H, Ext-RKSJ-V,
H, V, UniJIS-UCS2-H, UniJIS-UCS2-V, UniJIS-UCS2HW-H, UniJIS-UCS2-HW-V
KSC-EUC-H, KSC-EUC-V, KSCms-UHC-H, KSCmsUHC-V, KSCms-UHC-HW-H, KSCms-UHC-HW-V,
KSCpc-EUC-H, UniKS-UCS2-H, UniKS-UCS2-V
HYSMyeongJoStd-MediumAcro2
1. In Acrobat 4 verfügbar; in Acrobat 5 werden sie durch andere Schriften ersetzt.
2. Nur in Acrobat 5 verfügbar.
CJK-Schriftunterstützung in PDFlib. Wenn man sich die Gemeinsamkeiten zwischen
Standardschriften und Zeichensätzen einerseits sowie CJK-Standardschriften und
CMaps andererseits vor Augen führt, ist es nicht weiter verwunderlich, dass sowohl lateinische als auch CJK-Schriften mit der selben PDFlib-Schnittstelle ausgewählt werden
können. Der CMap-Name wird anstelle des Encodings übergeben. Außerdem ist zu berücksichtigen, dass eine CJK-Schrift nur eine bestimmte Menge von CMaps unterstützt
(siehe Tabelle 3.7). Damit in der PDFlib-ActiveX-Edition breite Zeichen verwendet werden können, muss der Parameter nativeunicode auf true gesetzt werden. Das Beispiel für
KozMinPro-Regular-Acro in Tabelle 3.7 wurde mit folgendem Code erzeugt:
font = oPDF.findfont("KozMinPro-Regular-Acro", "Ext-RKSJ-H", 0)
oPDF.set_text_pos x, y
oPDF.show ChrW(&H93FA) & ChrW(&H967B) & ChrW(&H8CEA)
In obigem Codefragment wird eine der japanischen Standardschriften gewählt, mit einer zu Shift-JIS kompatiblen CMap (Ext-RKSJ) und horizontaler Schreibrichtung (H). Der
1. Unter http://partners.adobe.com/asn/developer/typeforum/cidfonts.html finden Sie eine Fülle von Informationen zu
CID-Schriften inklusive Tabellen mit allen unterstützten Glyphen (suchen Sie nach »character collection«).
3.3 Textbehandlung
61
Tabelle 3.8 Vordefinierte CMaps für Japanisch/Chinesisch/Koreanisch (aus der »PDF Reference«)
Sprache
Unterstützte CMaps
Vereinfachtes GB-EUC-H
Chinesisch
GB-EUC-V
Traditionelles
Chinesisch
Japanisch
Koreanisch
62
Beschreibung
Microsoft Codepage 936 (lfCharSet 0x86), GB 2312-80-Zeichensatz, EUCCN-Encoding
GBpc-EUC-H
GBpc-EUC-V1
Macintosh, GB-312-80-Zeichensatz, EUC-CN-Encoding, Script Manager
Code 2
GBK-EUC-H1
GBK-EUC-V1
Microsoft Codepage 936 (lfCharSet 0x86), GBK-Zeichensatz, GBK-Encoding
GBKp-EUC-H2
GBKp-EUC-V2
Wie GBK.EUC-H, ersetzt aber lateinische Zeichen halber Breite durch
proportionale Zeichen und ordnet dem Zeichencode 0x24 das
Dollarzeichen ($) statt des Yuan-Symbols (¥) zu.
GBK2K-H2
GBK2K-V2
GB-18030-2000-Zeichensatz, gemischtes 1-, 2- und 4-Byte-Encoding
UniGB-UCS2-H1
UniGB-UCS2-V1
Unicode-Encoding (UCS-2) für die Character-Collection Adobe GB1
B5pc-H
B5pc-V
Macintosh, Big-Five-Zeichensatz, Big-Five-Encoding, Script Manager Code 2
HKscs-B5-H2
HKscs-B5-V2
Hong Kong SCS (Supplementary Character Set), eine Erweiterung von BigFive-Zeichensatz und -Encoding
ETen-B5-H
ETen-B5-V
Microsoft Codepage 950 (lfCharSet 0x88), Big-Five-Zeichensatz mit ETenErweiterungen
ETenms-B5-H1
ETenms-B5-V1
Wie ETen-B5-H, ersetzt aber lateinische Zeichen halber Breite durch
proportionale Zeichen
CNS-EUC-H
CNS-EUC-V
CNS-11643-1992-Zeichensatz, EUC-TW-Encoding
UniCNS-UCS2-H1
UniCNS-UCS2-V1
Unicode-Encoding (UCS-2) für die Character-Collection Adobe-CNS1
83pv-RKSJ-H
Macintosh, JIS-X-0208-Zeichensatz mit KanjiTalk6-Erweiterungen, ShiftJIS-Encoding, Script Manager Code 1
90ms-RKSJ-H
90ms-RKSJ-V
Microsoft Codepage 932 (lfCharSet 0x80), JIS-X-0208-Zeichensatz mit
NEC- und IBM-Erweiterungen
90msp-RKSJ-H1
90msp-RKSJ-V1
Wie 90ms-RKSJ-H, ersetzt aber lateinische Zeichen halber Breite durch
proportionale Zeichen
90pv-RKSJ-H
Macintosh, JIS-X-0208-Zeichensatz mit KanjiTalk7-Erweiterungen, ShiftJIS-Encoding, Script Manager Code 1
Add-RKSJ-H
Add-RKSJ-V
JIS-X-0208-Zeichensatz mit Fujitsu FMR-Erweiterungen, Shift-JIS-Encoding
EUC-H1
EUC-V1
JIS-X-0208-Zeichensatz, EUC-JP-Encoding
Ext-RKSJ-H
Ext-RKSJ-V
JIS-C-6226-Zeichensatz (JIS78) mit NEC-Erweiterungen, Shift-JIS-Encoding
H
V
JIS-X-0208-Zeichensatz, ISO-2022-JP-Encoding
UniJIS-UCS2-H1
UniJIS-UCS2-V1
Unicode-Encoding (UCS-2) für die Character-Collection Adobe Japan1
UniJIS-UCS2-HW-H1
UniJIS-UCS2-HW-V1
Wie UniJIS-UCS2-H, ersetzt aber proportionale lateinische Zeichen durch
Zeichen halber Breite
KSC-EUC-H
KSC-EUC-V
KS-X-1001:1992-Zeichensatz, EUC-KR-Encoding
KSCms-UHC-H
KSCms-UHC-V
Microsoft Codepage 949 (lfCharSet 0x81), KS-X-1001:1992-Zeichensatz plus
8822 zusätzliche Hangul-Zeichen, Unified-Hangul-Code-Encoding (UHC)
Tabelle 3.8 Vordefinierte CMaps für Japanisch/Chinesisch/Koreanisch (aus der »PDF Reference«)
Sprache
Unterstützte CMaps
Beschreibung
KSCms-UHC-HW-H1
KSCms-UHC-HW-V1
Wie KSCms-UHC-H, ersetzt aber proportionale lateinische Zeichen durch
Zeichen halber Breite
KSCpc-EUC-H
Macintosh, KS-X-1001:1992-Zeichensatz mit Mac-OS-KH-Erweiterungen,
Script Manager Code 3
UniKS-UCS2-H1
UniKS-UCS2-V1
Unicode-Encoding (UCS-2) für die Character-Collection Adobe-Korea1
1. Erst ab PDF 1.3 / Acrobat 4 verfügbar.
2. Erst ab PDF 1.4 / Acrobat 5 verfügbar.
Parameter fontname muss den genauen Schriftnamen enthalten (genauer gesagt, den
Wert des Eintrags /CIDFontName in der zugehörenden CID-PostScript-Zeichenbeschreibungsdatei), 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 unten). PDFlib unterstützt alle standardmäßig in Acrobat enthaltenen CMaps und beschwert sich, wenn Schrift und CMap nicht zusammenpassen. Wenn
Sie PDFlib zum Beispiel anweisen, eine koreanische Schrift mit einem japanischen Zeichensatz zu verwenden, wird eine Exception vom Typ ValueError ausgelöst.
Technisch gesehen ist die Einbettung von CID-Schriften in PDF 1.3 zwar möglich, aber
kaum praktikabel wegen der Größe einer CID-Schrift und der Tatsache, dass die meisten
CJK-Schriftlizenzen eine Einbettung untersagen. Aus diesem Grund wird der Parameter
embed bei CID-Schriften nicht verwendet und muss den Wert 0 haben.
PDFlib benötigt für CID-Schriften keine schriftspezifischen Metrikdaten und unternimmt auch keinerlei Versuche, die vom Client übergebenen Textstrings zu dekodieren
oder zu überprüfen, ob sie hinsichtlich der zugrunde liegenden CMap korrekt kodiert
sind. Aus diesem Grund werden die folgenden Funktionen für CID-Schriften derzeit
nicht unterstützt:
> Berechnen der Textbreite mit stringwidth( )
> Formatierung von Text in ein Rechteck mit show_boxed( )
> Aktivierung der Modi für Unterstreichen, Überstreichen und Durchstreichen
> Ermittlung der textx/texty-Position
Hinweis PDFlib unterstützt gegenwärtig nur die CID-Standardschriften, die mit Acrobat mitgeliefert
werden (siehe Tabelle 3.7). Es können keine benutzerdefinierten CID-Schriften und auch keine
japanischen, chinesischen oder koreanischen TrueType-Schriften verwendet werden. Fette
Schriftschnitte lassen sich aber über den Rendering-Modus 2 simulieren (siehe Parameter textrendering).
CJK-Zeichenbreiten. PDFlib geht davon aus, dass alle einschließlich der lateinischen
Zeichen in CJK-Schriften die gleiche Breite besitzen. Die Zeichenbreite entspricht der
Schriftgröße. PDFlib unterstützt für CJK-Schriften bislang kein Konzept der halben und
vollen Zeichenbreite. Sollen Ihre lateinischen Zeichen schmaler sein als die CJK-Zeichen,
müssen Sie zu einer lateinischen 8-Bit-Schrift wie zum Beispiel Courier oder Helvetica
wechseln.
Horizontale und vertikale Schreibrichtung. PDFlib unterstützt sowohl horizontale als
auch vertikale Schreibrichtung. Der entsprechende Modus wird über einen geeigneten
3.3 Textbehandlung
63
CMap-Namen ausgewählt. Diese zeigen durch die Endung -H bzw. -V an, dass sie eine horizontale bzw. vertikale Schreibrichtung vorgeben.
Hinweis Bei manchen PDFlib-Funktionen muss die Semantik an die jeweilige Schreibrichtung angepasst
werden. Beispielsweise sollte 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
Funktionsbeschreibungen.
Zeichencodes für CJK-Text in PDFlib. Text muss vom Client so übergeben werden, dass
die Zeichencodes dem Zeichensatz für die CID-Schrift entsprechen. PDFlib überprüft
nicht, ob der übergebene Text dem geforderten Zeichensatz entspricht. Bei MultibyteZeichensätzen muss das höchstwertige Byte vorne stehen.
Die PDFlib-Sprachbindungen, die native Unicode-Unterstützung bieten(inklusive
ActiveX/COM), konvertieren an die Bibliothek übergebene Unicode-Strings automatisch. Aus diesem Grund sollten Unicode-kompatible CMaps nur mit diesen Sprachbindungen verwendet werden, wenn der Parameter nativeunicode auf true gesetzt ist (siehe
auch Abschnitt 3.3.9, »Unicode-Unterstützung«, Seite 65).
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 hinaus ginge. Wir möchten jedoch einige Hinweise geben, die dem PDFlib-Benutzer nützlich sein können. Wenn Sie beim Drucken von CJK-Dokumenten mit Acrobat Probleme
haben, sollten Sie folgende Ursachen in Betracht ziehen:
> CID-Schriften können nicht auf allen PostScript-Druckern ausgegeben werden. Native Unterstützung für CID-Schriften 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 (sofern sie nicht mit den Type-0-Schrifterweiterungen ausgestattet sind).
Bei frühen Level-2-Geräten kann man aber davon ausgehen, dass der Druckertreiber
passende Kompatibilitätsroutinen an Level-2-Drucker vor Version 2015 lädt.
> Aufgrund der immensen Anzahl von Zeichen benötigen CID-Schriften enormen Druckerspeicher (CID-Fontdateien beanspruchen in der Regel 5 bis 10 MB auf der Festplatte). Nicht alle Drucker verfü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 aufrüsten, um PDF-Dokumente mit CID-Schriften 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, aktivieren Sie die Option Als Bild drucken. Acrobat sendet dann eine Rasterbildversion der
Seite an den Drucker (allerdings mit 300 dpi).
64
3.3.9 Unicode-Unterstützung
Seit Version 4 unterstützt Acrobat den Unicode-Standard, der
im wesentlichen ISO 106461 entspricht. Unicode ist ein riesiger
Zeichensatz, der alle weltweit gegenwärtig verwendeten und
viele alte Sprachen und Schriften umfasst und in vielen Anwendungen und Betriebssystemen unterstützt wird. PDFlib bietet
Unicode-Unterstützung bei folgenden Funktionen:
> Lesezeichen (siehe Abbildung 3.2)
> Inhalt und Titel von Notizen (siehe Abbildung 3.2)
> Inhalt von vor- und benutzerdefinierten Dokumentinfofeldern (nicht jedoch die Namen von benutzerdefinierten Feldern – das wird durch die PDF-Spezifikation unterbunden)
> Beschreibung und Verfasser von Dateianlagen
> CJK-Text auf Seitenbeschreibungen, falls ein Unicode-kompatibler Zeichensatz verwendet wird (siehe Abschnitt 3.3.8, »Japanischer, chinesischer und koreanischer
Text«, Seite 60)
> 8-Bit-Codepages für TrueType-, PostScript- und OpenType-Schriften
Bevor wir näher auf die Unicode-Implementierung eingehen, sollten Sie sich folgende
Einschränkungen der Unicode-Unterstützung in Acrobat klar machen:
> Acrobat 4 zeigt nicht alle Zeichen der Adobe Glyph List korrekt an (dieser Fehler ist in
Acrobat 5 behoben). Das Problem zeigt sich zum Beispiel bei kyrillischen Zeichen.
> Der Einsatz von PDF-Dokumenten mit Unicode hängt maßgeblich von der UnicodeUnterstützung des Zielsystems ab. Leider bieten die wenigsten derzeit verfügbaren
Systeme in der Standardkonfiguration volle Unicode-Unterstützung. Windows NT/
2000/XP und Mac OS unterstützen Unicode zwar intern, ein Problem bleibt jedoch
die mangelhafte Verfügbarkeit geeigneter Unicode-Schriften.
> Unter Windows kann Acrobat in einer Anmerkung nur eine einzige Unicode-Schrift
verwenden. Dies scheint mit einem betriebssystemspezifischen Problem zu tun zu
haben (nämlich mit Einschränkungen des in der Acrobat-Implementierung verwendeten Texteingabefelds der Anmerkungsfunktion).
Unicode-Codepages für PostScript- und TrueType-Schriften. PDFlib unterstützt Unicode in Seitenbeschreibungen für alle Zeichen, die in der Adobe Glyph List (AGL) verzeichnet sind. Während Textstrings noch 8-Bit-Zeichen enthalten müssen, kann eine
beliebige Anzahl von bis zu maximal 256 Zeichen mittels einer auf Unicode basierenden
Codepagedefinitionsdatei ausgewählt werden. Diese Art der Unicode-Unterstützung ist
für TrueType-Schriften verfügbar, die auf Unicode basieren, sowie für PostScript-Schriften mit Glyphennamen in der AGL. Weitere Informationen über Codepages und die AGL
finden Sie in Abschnitt 3.3.3, »Benutzerdefinierte 8-Bit-Zeichensätze und Codepages«,
Seite 48.
Unicode-Zeichensätze für CID-Schriften. PDF erlaubt Unicode-kodierten Text auf Dokumentseiten (im Gegensatz zum oben erwähnten Hypertext). Leider gilt dies nur für
CID-Schriften, nicht aber für normale PostScript-Type-1-Schriften. Um Unicode-konformen chinesischen, japanischen oder koreanischen Text auf einer Seite zu platzieren,
1. Siehe http://www.unicode.org
3.3 Textbehandlung
65
Abb. 3.2 Unicode-Lesezeichen (links) und Unicode-Notizen (rechts)
muss eine Unicode-kompatible CMap verwendet werden. Solche CMaps sind einfach am
Präfix Uni im Namen zu erkennen (siehe Tabelle 3.8). Sie unterstützen aber nur diejenigen Zeichen, die für die jeweilige Sprache erforderlich sind, und keine anderen UnicodeZeichen.
PDF_PDF_Unicode-Zeichensatz für Hypertextelemente. Benutzer der PDFlib-ActiveXEdition können an die Unicode-fähigen Hypertextfunktionen (Lesezeichen, Anmerkungen etc.) direkt UCS-2-kodierten Unicode-Text übergeben, sofern der Parameter nativeunicode auf true gesetzt ist. Das folgende Codefragment (in hexadezimaler Schreibweise)
erstellt zum Beispiel ein Lesezeichen mit dem griechischen String Λ ΟΓ ΟΣ (siehe Abbildung 3.2):
bookmark = oPDF.add_bookmark(ChrW(&H39B) & ChrW(&H39F) & ChrW(&H393) & ChrW(&H39F) &_
ChrW(&H3A3), 0, 0)
Falsche Unicode-Zeichenzuordnungen unter Windows. Folgende PDFlib-Sprachbindungen sind Unicode-fähig und können Unicode-Strings automatisch in das von PDFlib
erwartete Format konvertieren:
> ActiveX/COM
> Java (abhängig von den Spracheinstellungen)
> .NET
> Tcl (erfordert Tcl ab 8.2)
Um das unten beschriebene Problem bei der Zeichenkonvertierung zu vermeiden, ist
die Unicode-Unterstützung bei diesen Sprachbindungen standardmäßig deaktiviert.
Zur Aktivierung setzen Sie den PDFlib-Parameter nativeunicode auf true (siehe auch Abschnitt 4.3.2, »Textausgabe«, Seite 92):
66
Der Parameter nativeunicode bedeutet, dass der Wrapper-Code intern folgende Fälle unterscheidet und die jeweils passende Konvertierung anwendet:
> 8-Bit-Strings, also Strings, die nur Zeichen zwischen U+0000 to U+00FF enthalten,
werden (für Hypertext) als PDFDocEncoding interpretiert oder als 8-Bit-Zeichen gemäß des aktuellen Zeichensatzes (für Seitenbeschreibungen).
> Unicode-Strings für Hypertextfunktionen werden gemäß der PDF-Referenz kodiert .
Unicode-Strings müssen gemäß UCS-2 kodiert sein. UTF-8-Kodierung wird gegenwärtig nicht unterstützt.
> Unicode-Strings für Seitenbeschreibungen werden ohne jede Konvertierung übergeben. Dazu muss eine Unicode-kompatible CMap selektiert sein (siehe Tabelle 3.7).
Entwickler brauchen sich generell nicht um die oben ausgeführten Zeichensatzdetails
zu kümmern, sondern können einfach mit dem von der jeweiligen Umgebung unterstützten Unicode-Text arbeiten. (Weitere Informationen über die Verwendung von Unicode innerhalb der verwendeten Sprachen finden Sie in Kapitel 2 bei der Beschreibung
der jeweiligen Sprachbindungen). Es gibt jedoch ein subtiles Problem in Bezug auf in
ActiveX-, Java-, .NET- oder Tcl-Quellcode eingebettete literale Unicode-Zeichen, das wir
an einem kleinen Beispiel erläutern möchten.
Die native Unterstützung von COM oder .NET für Unicode-Strings funktioniert wunderbar bei den Hypertextelementen von PDF, kann aber bei Seitenbeschreibungen und
8-Bit-Zeichensätzen, die nicht Unicode-kompatibel sind, problematisch sein. So sind
zum Beispiel die meisten, aber nicht alle Zeichen der Windows-Codepage 1252 kompatibel (genauer gesagt, ist der Bereich &H80–&H9F nicht kompatibel). Betrachten Sie folgenden Versuch, den Gedankenstrich mit PDFlib anzuzeigen:
' Literales Zeichen &H96 = Alt-150 im Code. Funktioniert nur bei nativeunicode = false
oPDF.show("–");
Wird diese Zeile unter Windows mit Codepage 1252 und nativeunicode == true verwendet,
wird das literale Zeichen für den Gedankenstrich (&H96 in der Codepage 1252) in das
entsprechende Unicode-Zeichen konvertiert (&H2013 in diesem Beispiel), was für einen
8-Bit-PDF-Zeichensatz wie winansi völlig ungeeignet ist. Um diesem Problem bei aktiviertem »nativem Unicode« vorzubeugen, ist die obige Zeile wie folgt umzuformulieren:
' Problemlose Zeichenauswahl außerhalb Latin-1 bei nativeunicode = true
oPDF.show ChrW(&H96)
Damit wird der Code &H96 für das gewünschte Zeichen an PDFlib übergeben und dort
korrekt gemäß des gewählten Zeichensatzes interpretiert.
3.3.10 Textmetrik, Textvarianten und Formatierung in ein Rechteck
Textposition. PDFlib verwaltet eine aktuelle Textposition, die unabhängig von dem
aktuellen Punkt ist, der beim Zeichnen von Grafik verwendet wird. Die aktuelle Textposition kann über die Parameter textx/texty und der aktuelle Punkt über currentx/currenty
abgefragt werden.
Schrift- und Zeichenmetrik. PDFlib verwendet dasselbe System für Zeichen- und Fontmetriken wie PostScript und PDF. Es soll hier kurz beschrieben werden.
3.3 Textbehandlung
67
Die Schriftgröße, die von PDFlib-Anwendern festgelegt werden muss, ist der Abstand
zwischen zwei aufeinanderfolgenden Textzeilen, der minimal erforderlich ist, damit
keine Zeichen teilweise ü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 Zwischenraum zwischen den Zeilen umfasst.
Der Zeilenabstand (leading, line spacing) bezeichnet den vertikalen Abstand zwischen
den Grundlinien 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 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 gemessen und müssen deshalb vor der Verwendung mit der nötigen
Schriftgröße multipliziert werden.
Die Werte für Versalhöhe, Oberlänge und Unterlänge für eine bestimmte Schrift sind
in der Fontmetrikdatei enthalten und können wie folgt von PDFlib abgefragt werden:
font = oPDF.findfont("Times-Roman", "winansi", 0)
oPDF.setfont font, fontsize
capheight = oPDF.get_value("capheight", font) * fontsize
ascender = oPDF.get_value("ascender", font) * fontsize
descender = oPDF.get_value("descender", font) * fontsize
Hinweis Position und Größe von hochgestellten und tiefgestellten Zeichen kann von PDFlib nicht abgefragt werden, da diese Informationen in AFM-Metrikdateien nicht verfügbar sind.
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, wobei der volle Zeichenbereich auf 1000 Einheiten pro Punkt festgelegt ist (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
Abb. 3.3 Font- und Zeichenmetrik
Fontgröße
(font size)
Grundlinie
(baseline)
68
Versalhöhe
(capheight)
Oberlänge
(ascender)
Unterlänge (descender)
bei einem optimalen Zeilenabstand von 12 Punkt. Da ein Zoll (inch) aus 72 Punkt besteht, 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 Zeichenbreite 6 Punkt, was eine 72/6 = 12 cpi Schrift ergibt; 8 Punkt Courier ergibt 15 cpi.
oPDF.set_parameter "kerning", "false"
' Kerning deaktivieren
Unterstreichen, Überstreichen und Durchstreichen von Text. PDFlib kann angewiesen
werden, Linien unter, über oder auf Text zu 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 set_parameter( ) lässt sich das Unter-, Über- oder
Durchstreichen wie folgt ein- und ausschalten:
oPDF.set_parameter "underline", "true"
' Unterstreichen aktivieren
Die Striche erhalten die aktuelle Zeichenfarbe, die aktuellen Parameter für Linienenden
und Strichmuster werden dagegen ignoriert. Warnung für Ästhethen: 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 CID-Schriften nicht unterstützt.
Modi der Textdarstellung. PDFlib unterstützt mehrere Darstellungsmodi, die das Erscheinungsbild von Text beeinflussen. Dazu gehört Text, der durch Umrisslinien dargestellt wird, sowie die Möglichkeit, Text als Clipping-Pfad zu verwenden. Text lässt sich
auch unsichtbar darstellen. Dies mag zum Beispiel sinnvoll sein, um Text auf eingescannten Bildern zu platzieren, so dass er zwar indiziert und durchsucht werden kann,
aber nicht direkt sichtbar ist. Tabelle 3.9 zeigt die Darstellungsmodi, die mit set_value( )
gesetzt werden können.
Tabelle 3.9 Werte für den Textdarstellungsmodus
Wert
Erklärung
Wert
Erklärung
0
Umrisslinien füllen (normaler Text)
4
Umrisslinien füllen und zum Clipping-Pfad
hinzufügen
1
Umrisslinien zeichnen
5
Umrisslinien zeichnen und zum Clipping-Pfad
hinzufügen
2
Umrisslinien sowohl zeichnen als
auch füllen
6
Umrisslinien sowohl zeichnen als auch füllen und
zum Clipping-Pfad hinzufügen
3
unsichtbarer Text
7
Umrisslinien zum Clipping-Pfad hinzufügen
oPDF.set_value "textrendering", 1
' Umrisslinien zeichnen
Textfarbe. Text wird gewöhnlich mit der aktuellen Füllfarbe dargestellt, die mit
setcolor( ) gesetzt werden kann. Bei einem von 0 verschiedenen Darstellungsmodus werden je nach Modus die Linien- und die Füllfarbe verwendet.
Formatierung von Text in ein Rechteck. PDFlib bietet zwar die Funktion stringwidth( )
zur Berechnung der Textbreite, viele Clients benötigen aber eine einfache Möglichkeit
zur Textboxformatierung, um zum Beispiel einen Text in eine vorgegebene Spalte ein-
3.3 Textbehandlung
69
In an attempt to reproduce sounds more accurately, pinyin
spellings often differ markedly from the older ones, and
personal names are usually spelled without apostrophes or
hyphens; an apostrophe is sometimes used, however, to
avoid ambiguity when syllables are run together (as in
Chang´an to distinguish it from Chan´gan).
Abb. 3.4 Formatierung von Text in ein Rechteck: Die untere Kante dient als letzte Grundlinie, nicht als Clipping-Grenze.
zupassen. PDFlib bietet zwar entsprechende Funktionen, man darf sich die Bibliothek
aber nicht als vollständiges Layoutprogramm vorstellen. Die Funktion show_boxed( )
bietet eine bequeme Methode zur Formatierung von Text in ein Rechteck einschließlich
einer Reihe von Formatierungsoptionen. Der Text kann in einer rechteckigen Box linksbündig, rechtsbündig, zentriert oder im Blocksatz ausgerichtet werden. Die erste Textzeile beginnt an einer Grundlinie, deren vertikale Position der Oberkante der übergebenen Box minus dem Zeilenabstand entspricht. Die Unterkante der Box dient als letzte
Grundlinie. Aus diesem Grund können sich Unterlängen der letzten Textzeile außerhalb der Box befinden (siehe Abbildung 3.4).
Die Ausrichtung erfolgt durch Anpassung des Wortabstandes (die letzte Zeile bleibt
dabei linksbündig ausgerichtet). Dazu muss der Text natürlich Leerzeichen enthalten
(sind keine Leerzeichen vorhanden, fügt PDFlib auch keine ein). Komplexe Textverarbeitungsfunktionen wie Silbentrennung sind nicht verfügbar – PDFlib bricht den Text
einfach an den vorhandenen Leerzeichen um. Der Text wird an den Rändern des Rechtecks keinesfalls beschnitten.
Wenn Sie im Parameter feature den Wert blind übergeben, können Sie feststellen, ob
ein String in eine bestimmte Box passt, ohne dass eine Ausgabe erzeugt wird.
ASCII-Zeichen für Newline (ox0A, in VBScript: vbCrLf) werden im übergebenen Text erkannt und bewirken einen neuen Absatz. CR/NL-Kombinationen werden wie ein einzelnes Newline-Zeichen behandelt. Andere Formatierungszeichen (insbesondere Tabulatoren) werden nicht unterstützt.
Es folgt ein kleines Beispiel zum Einsatz der Funktion show_boxed( ). Es zeichnent mit
rect( ) einen zusätzlichen Rahmen um die Box, der bei der Fehlersuche hilfreich sein
kann:
Text = "In an attempt to reproduce sounds more accurately, pinyin spellings often ... "
fontsize = 13
font = oPDF.findfont("Helvetica", "host", 0)
oPDF.setfont font, fontsize
x
y
w
h
=
=
=
=
50
650
357
6 * fontsize
c = oPDF.show_boxed(Text, x, y, w, h, "justify", "")
If (c > 0) Then
' Nicht alle Zeichen konnten im Rechteck platziert werden; darauf reagieren
...
End If
70
oPDF.rect x, y, w, h
oPDF.stroke
Folgende Voraussetzungen und Einschränkungen der Funktion show_boxed( ) sind zu
erwähnen:
> Der Text sollte keine aufeinander folgenden Leerzeichen enthalten.
> Wegen diverser Einschränkungen in der Unterstützung des Wortabstandes bei PDF
muss sich das Leerzeichen im Zeichensaztz an Position &H20 befinden. Dies ist zwar
bei den meisten gängigen Zeichensätzen der Fall, die Ausrichtung funktioniert damit aber beim EBCDIC-Zeichensatz nicht.
> Der einfache Formatierungsalgorithmus kann bei unpassenden Kombinationen aus
langen Wörtern und engen Spalten scheitern, da es keinen Algorithmus zur Silbentrennung gibt.
> Da der untere Teil des Rechtecks als Grundlinie verwendet wird, können Unterlängen in der letzten Zeile aus dem Rechteck hinausreichen.
> Es ist nicht sehr intuitiv, PDF_show_boxed( ) mit in der linken oberen Ecke ausgehenden Koordinaten zu verwenden. Beachten Sie hierzu Abschnitt 3.2.1, »Koordinatensysteme«, Seite 40.
> Es ist gegenwärtig nicht möglich, Text in mehreren Portionen an die Routine zur Formatierung in ein Rechteck zu übergeben. Sie können die nach dem Aufruf von PDF_
show_boxed( ) aktuelle Textposition aber mit den Parametern textx und texty ermitteln.
> Die Schrift kann innerhalb des Rechtecks nicht geändert werden.
> Die Formatierung von Text in ein Rechteck wird für CID-Schriften/CJK-Zeichensätze
nicht unterstützt.
3.4 Verwendung von Rasterbildern
3.4.1 Unterstützte Rasterbildformate
Die Einbettung von Rasterbildern in das generierte PDF-Dokument stellt eine wesentliche Funktion von PDFlib dar. PDFlib verarbeitet gegenwärtig alle Rasterbildformate, die
unten beschrieben werden. Bei den meisten Formaten reicht PDFlib die komprimierten
Bilddaten unverändert an die PDF-Ausgabe weiter, da PDF intern die meisten in Rasterbildformaten verwendeten Kompressionsverfahren unterstützt. Diese Technik (in den
folgenden Beschreibungen Pass-Through-Modus genannt) bewirkt einen äußerst schnellen Bildimport, da die Dekompression und die darauf folgende erneute Kompression
der Bilddaten entfallen. In diesem Modus kann PDFlib die Integrität der komprimierten
Bilddaten nicht überprüfen. Unvollständige oder beschädigte Daten bewirken Fehleroder 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 und Sie Einzelheiten über die Ursachen wissen möchten, dann setzen Sie den Parameter
imagewarning auf true (siehe Abschnitt 4.6, »Rasterbildfunktionen«, Seite 109):
oPDF.set_parameter "imagewarning", "true"
' Warnungen aktivieren
PNG-Bilder. PDFlib unterstützt alle Varianten von PNG-Bildern (Portable Network Graphics).1 PNG-Bilder werden meistens im Pass-Through-Modus verarbeitet. PNG-Bilder,
71
die das Zeilensprungverfahren (Interlacing) nutzen, einen Alphakanal enthalten (der in
jedem Fall verlorengeht, siehe unten) oder eine Farbtiefe von 16 Bit besitzen, müssen
dekomprimiert werden, was bedeutend länger dauert als der Pass-Through-Modus. Enthält ein PNG-Bild Transparenzinformationen, so bleibt diese im generierten PDF erhalten (siehe Abschnitt 3.4.5, »Bildmasken und Transparenz«, Seite 76). 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 von der überwiegenden Mehrheit der
JPEG-Bilder verwendet wird.
> Progressive-Kompressionsmodus von JPEG, der seit Acrobat 4/PDF 1.3. unterstützt
wird. Im Kompatibilitätsmodus für Acrobat 3 lehnt PDFlib den Import von JPEG-Bildern mit »Progressive«-Kompression ab.
JPEG-Bilder können in unterschiedlichen Dateiformaten verpackt sein. PDFlib unterstützt alle gängigen JPEG-Dateiformate und ermittelt Auflösungswerte aus den folgenden 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.
PDFlib interpretiert die Auflösungsinformationen von JPEG-Bildern im Dateiformat
SPIFF nicht.
GIF-Bilder. GIF-Bilder werden immer im Pass-Through-Modus verarbeitet (PDFlib benutzt keine LZW-Dekompression). PDFlib unterstützt folgende Arten von GIF-Bildern:
> Wegen der Einschränkungen in den vom PDF-Dateiformat unterstützten Kompressionsverfahren muss der Eintrag LZW minimum code size in der GIF-Datei den Wert 8 Bit
haben. Leider gibt es keine einfache Möglichkeit, diesen Wert für eine vorliegende
Datei zu ermitteln. Ein Bild, das mehr als 128 unterschiedliche Farbwerte enthält, ist
immer geeignet (zum Beispiel eine vollständige 8-Bit-Farbpalette mit 256 Einträgen).
Bilder mit einer geringeren Anzahl verschiedener Farben können auch geeignet sein,
aber dies lässt sich nur schwer im vorhinein entscheiden, da Grafikprogramme in
diesem Fall 8 Bit oder weniger als minimale LZW-Codelänge verwenden können, und
PDFlib das Bild nur bei weniger ablehnt. Mit dem folgenden Trick, der in Adobe Photoshop und ähnlichen Bildbearbeitungsprogrammen funktioniert, lassen sich GIFBilder erstellen, die von PDFlib akzeptiert werden: Laden Sie das GIF-Bild und ändern
Sie den Farbmodus von indiziertes Bild auf RGB. Nun ändern Sie den Farbmodus wieder zu »indiziertes Bild«, wobei Sie eine Farbpalette mit mehr als 128 Einträgen wählen, zum Beispiel die Mac- oder Windows-Systempalette oder die Web-Palette.
> Es muss ein non-interlaced GIF sein.
> Bei einem animierten GIF wird nur das erste Bild importiert.
Bei anderen GIF-Varianten ist eine Konvertierung in das PNG-Format empfehlenswert.
1. Siehe http://www.w3.org/Graphics/PNG und http://www.libpng.org/pub/png
72
Hinweis In einem unserer Tests wurde ein GIF-Bild von PDFlib in eine PDF-Datei konvertiert, die zwar
korrekt angezeigt wurde, aber bei der Ausgabe auf einem PostScript-Level-2- oder Level-3-Drucker zu einem PostScript-Fehler führte. Da das Problem bei Ghostscript nicht auftritt, gehen wir
von einem Fehler im PostScript-Interpreter aus. Das Problem lässt sich umgehen, indem im
Druckdialog von Acrobat bei den PostScript-Einstellungen als Druckmethode Level 1 ausgewählt wird.
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), LZW und PackBits (=RunLength). Diese Varianten werden im Pass-Through-Modus verarbeitet; andere Varianten werden dekomprimiert.
> Farbtiefe: schwarzweiß, Graustufen, RGB und CMYK; ein gegebenenfalls vorhandener Alphakanal wird ignoriert.
> TIFF-Dateien, die aus mehreren Bildern bestehen (siehe Abschnitt 3.4.7, »Mehrseitige
Bilddateien«, Seite 80)
> Die Farbtiefe muss bei 1, 2, 4 oder 8 Bit pro Farbwert liegen (dies ist eine Anforderung
von PDF).
TIFF-Bilder mit mehreren Streifen (multi-strip) werden zu mehreren Bildern in der PDFDatei konvertiert, die genau wie das Original aussehen, aber mit dem TouchUpObjektwerkzeug getrennt selektiert werden können. Diese Art von TIFF-Bildern lässt
sich mit dem Befehlszeilenprogramm tiffcp aus dem TIFFlib-Paket1 in Bilder mit einem
Streifen (»single-strip«) umwandeln. Das Tool ImageMagick2 erzeugt prinzipiell singlestrip TIFF-Bilder.
Manche TIFF-Eigenschaften (zum Beispiel CIE-Farbraum oder JPEG-Kompression)
und bestimmte Merkmalskombinationen (zum Beispiel LZW-Kompression und Alphakanal, LZW-Kompression und Kachelung) werden nicht unterstützt.
Hinweis Bestimmte Varianten von TIFF-Bildern, die mit CCITT Gruppe 3 komprimiert sind und mit PDFlib
konvertiert werden, bewirken in Acrobat 4 unter Umständen die Meldung »Nicht genügend
Daten für ein Bild«. Da das Problem weder in Ghostscript noch in Acrobat 5 auftritt und das Bild
trotz der Fehlermeldung korrekt angezeigt wird, gehen wir hier von einem Fehler in Acrobat 4
aus. Sie können das Problem umgehen, indem Sie ein anderes Kompressionsverfahren für das
TIFF-Bild verwenden.
CCITT-Bilder. Mit Gruppe 3 oder Gruppe 4 komprimierte Faxdaten 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-Dateien mit CCITT-Kompression. Mit CCITT komprimierte Rohbilddaten werden in Anwendungen für Endbenutzer normalerweise nicht unterstützt und können nur mit Faxsoftware generiert werden.
Rohdaten. Nicht komprimierte Bilddaten (Rohbilddaten) mögen in speziellen Fällen
sinnvoll sein, zum Beispiel beim Aufbau eines Farbverlaufs im Arbeitspeicher. Die Art
des Bildes leitet sich aus der Anzahl der Farbkomponenten ab: eine Komponente impli1. Siehe http://www.libtiff.org
2. Siehe http://www.imagemagick.org
73
ziert ein Graustufenbild, drei Komponenten implizieren ein RGB-Bild und vier Komponenten ein CMYK-Bild.
3.4.2 Häufig benötigte Codefragmente für Rasterbilder
Die Einbettung von Rasterbildern mit PDFlib ist einfach zu bewerkstelligen. Die Bilddatei muss zunächst mit einer PDFlib-Funktion geöffnet werden, die eine kurze Analyse
der Bildparameter durchführt. Die Funktion PDF_open_image_file( ) gibt ein Handle zurück, das als Bilddeskriptor dient. Es kann zusammen mit Positionierungs- und Skalierungsparametern im Aufruf von PDF_place_image( ) verwendet werden:
lImage = oPDF.open_image_file("jpeg", "image.jpg", "", 0)
If (lImage = -1) Then
MsgBox "Bilddatei konnte nicht geöffnet werden."
End
Else
oPDF.close_image lImage
End If
Der Aufruf von PDF_close_image( ) ist an dieser Stelle nur bedingt erforderlich, je nachdem, ob das Bild im Dokument ein weiteres Mal verwendet wird (siehe Abschnitt 3.4.3,
»Wiederverwendung von Bilddaten«, Seite 76).
Skalierung und dpi-Berechnung. PDFlib ändert die Pixelanzahl eines importierten Bildes nie. Beim Skalieren werden die Bildpunkte entweder vergrößert oder verkleinert, es
findet jedoch keinerlei Downsampling statt. Der Skalierungsfaktor 1 bewirkt eine Pixelgröße von einer Einheit in benutzerspezifischen Koordinaten. Anders ausgedrückt wird
das Bild mit 72 dpi importiert, wenn das benutzerspezifische Koordinatensystem nicht
skaliert wurde (da ein Zoll 72 Punkt entspricht).
Die dpi-Werte für die Auflösung, die in der ursprünglichen Bilddatei gegebenenfalls
enthalten sind, werden von PDFlib ignoriert, können aber mit den Parametern resx und
resy abgefragt werden; der Benutzer ist für eine geeignete Skalierung des Koordinatensystems verantwortlich (achten Sie auf Bilder mit nicht-quadratischen Pixeln). Der folgende Algorithmus kann verwendet werden, um ein Bild mit der Auflösung zu importieren, die in der Datei angegeben ist (oder mit 72 dpi, wenn die Datei über keinen dpiWert verfügt), und dessen Größe und Position so festlegen, dass es die ganze Seite einnimmt:
’ dpi-Werte abfragen, sofern sie in der Bilddatei vorhanden sind
dpi_x = oPDF.get_value("resx", lImage)
dpi_y = oPDF.get_value("resy", lImage)
' Skalierungsfaktor aus
If (dpi_x > 0 And dpi_y
scale_x = 72# /
scale_y = 72# /
Else
If (dpi_x < 0 And dpi_y
scale_x = 1#
scale_y = dpi_y
Else
scale_x = 1#
scale_y = 1#
74
dpi-Werten berechnen, siehe Beschreibung von resx/resy
> 0) Then
' resx und resy in der Datei vorhanden
dpi_x
dpi_y
< 0) Then
' nur Verhältnis zw. resx und resy vorhanden
/ dpi_x
' keine Daten über resx und resy vorhanden
End If
End If
' Neue Seite anlegen, auf die das skalierte Bild exakt passt, und Bild platzieren
oPDF.begin_page oPDF.get_value("imagewidth", lImage) * scale_x, _
oPDF.get_value("imageheight", lImage) * scale_y
oPDF.[Scale] scale_x, scale_y
oPDF.place_image lImage, 0#, 0#, 1#
oPDF.end_page
Um statt des gegebenenfalls in der Bilddatei vorhandenen dpi-Werts einen festen dpiWert zu verwenden (zum Beispiel 300), ersetzen Sie die ersten beiden Zeilen des obigen
Codefragments durch:
dpi_x = 300
dpi_y = 300
' oder ein anderer Wert
Vorgeben der Druckgröße. Der folgende Algorithmus kann verwendet werden, um ein
Bild so auf einer PDF-Seite zu platzieren, dass es eine vorgegebene Breite width und
Höhe height erhält (statt wie im vorigen Algorithmus die Auflösung vorzugeben). Die
linke untere Ecke soll dabei an Position (x, y) liegen (alle Koordinaten in Punkt):
scale_x = lWidth / oPDF.get_value("imagewidth", lImage)
scale_y = lHeight / oPDF.get_value("imageheight", lImage)
oPDF.save
' Koordinatensystem skalieren, um Bildgröße an vorgegebenes Rechteck anzupassen
oPDF.[Scale] scale_x, scale_y
' Position muss unter Berücksichtigung der obigen Skalierung gewählt werden
oPDF.place_image lImage, x / scale_x, y / scale_y, 1
oPDF.restore
Nichtproportionale Bildskalierung. Da Bilder meist proportional skaliert werden (das
heißt, dass für Breite und Höhe derselbe Skalierungsfaktor verwendet wird), unterstützt
place_image( ) nur einen einzigen Skalierungsparameter, der auf beide Abmessungen
angewandt wird. Eine nicht-proportionale Skalierung lässt sich problemlos durch Skalierung des Koordinatensystems erreichen, die mit save/restore-Operationen geklammert ist, um andere Grafikoperationen nicht zu beeinträchtigen. Das folgende Codefragment platziert ein Bild, das auf 50 Prozent horizontal und auf 75 Prozent vertikal
skaliert ist:
oPDF.save
oPDF.[Scale] 0.5, 0.75
oPDF.restore
' ursprüngliches Koordinatensystem speichern
' Koordinaten, und damit das Bild skalieren
' ursprüngl. Koordinatensystem wiederherstellen
Beachten Sie, dass die an place_image( ) übergebenen x- und y-Werte ebenfalls der Skalierung mit PDF_scale( ) unterliegen; sie müssen deshalb mittels Division durch die Skalierungsfaktoren angepasst werden.
75
Ein Codefragment zur Platzierung von Bildern in einem Koordinatensystem mit Ursprung in der linken oberen Ecke finden Sie in Abschnitt 3.2.1, »Koordinatensysteme«,
Seite 40.
3.4.3 Wiederverwendung von Bilddaten
Es ist hervorzuheben, dass PDFlib ein wichtiges PDF-Verfahren zur optimalen Handhabung mehrfach vorkommender Rasterbilder unterstützt.
Betrachten wir zum Beispiel ein Layout, bei dem sich ein bestimmtes Logo oder ein
Hintergrund auf mehreren Seiten befindet. In solchen Fällen ist es möglich, die Bilddaten in der PDF-Datei nur einmal abzulegen und auf jeder Seite nur noch eine Referenz
darauf anzulegen. Dazu öffnen Sie die Bilddatei und rufen einfach place_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 unterschiedliche Skalierungsfaktoren verwenden (solange es nicht wieder geschlossen wird). Abhängig von der
Bildgröße und der Häufigkeit des Auftretens kann dieses Verfahren enormen Speicherplatz sparen.
3.4.4 Bilddaten im Speicher und externe Bildreferenzen
Bilddaten, die in PDFlib verwendet werden, stammen in aller Regel aus einer Datei, die
sich auf der Festplatte im lokalen Dateisystem befindet. Es werden aber auch andere
Bildquellen unterstützt. Denn aus Performancegründen kann es durchaus günstiger
sein, vorhandene Bilddaten direkt im Speicher zu übergeben statt auf die Festplatte zuzugreifen. PDFlib unterstützt direkt im Speicher vorgehaltene Bilddaten für einige Dateiformate.
PDFlib unterstützt zudem ein experimentelles Feature, das für PDF-Dateien in der
Regel Einsatz nicht zu empfehlen ist, in bestimmten Umgebungen aber vorteilhaft sein
kann. Während die meisten PDF-Dokumente alle benötigten Informationen selbst enthalten (mit Ausnahme nicht eingebetteter Schriften), ist es auch möglich, statt der eigentlichen Bilddaten nur eine Referenz auf eine externe Datenquelle zu speichern. Damit wird Acrobat die Verantwortung überlassen, die erforderlichen Bilddaten bei Bedarf
abzurufen. Dieses Verfahren ähnelt den Bildreferenzen, wie sie aus HTML-Dokumenten
bekannt sind. Als externe Bildquellen kommen in erster Linie Dateien im lokalen Dateisystem oder URLs in Frage. Dabei ist jedoch zu beachten, dass Referenzen auf Dateien in
Acrobat 3 und 4 funktionieren, während Referenzen auf URLs erst ab Acrobat 4 und nur
im Vollprodukt möglich sind. Das bedeutet, dass PDF-Dokumente mit Bild-URLs weder
in Acrobat 3 noch in Acrobat Reader 4/5 benutzbar sind!
Die Schnittstelle open_image( ) kann sowohl für Bilddaten direkt im Speicher als
auch für externe Referenzen verwendet werden.
3.4.5 Bildmasken und Transparenz
Transparenz in PDF. Transparenz hat in PostScript und PDF sehr lange gefehlt. Erst in
PDF 1.3 (und PostScript 3) integrierte Adobe eine gewisse, wenngleich eingeschränkte
Unterstützung für Transparenz in seine Sprachen und Anwendungen. Während Bildmasken (zum Auftragen von Farbe durch eine Bitmapmaske) in PostScript und PDF
schon lange unterstützt werden, gibt es seit Acrobat 4 eine Funktion zur Maskierung
einzelner Bildpunkte. Damit bieten sich folgende Möglichkeiten:
76
> Maskierung nach Position: Ein Bild kann die Information »drucke den Vordergrund,
aber nicht den Hintergrund« enthalten. Dieses Verfahren wird oft in Bildern für Kataloge verwendet.
> Maskierung nach Farbwert: Pixel einer bestimmten Farbe (oder eines bestimmten
Farbbereichs – aber nicht einer beliebig zusammengestellten Menge von Farben)
werden nicht gezeichnet, stattdessen scheint der vorher gezeichnete Teil der Seite
durch. 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.
Es ist wichtig anzumerken, dass PDF 1.3 keine echte, sondern lediglich zweiwertige
Transparenz unterstützt, in der weder ein Alphakanal noch ein weicher Übergang (»mische dieses Bild mit dem Hintergrund«) vorhanden ist, sondern nur eine EntwederOder-Entscheidung (»drucke das Pixel im Bild oder drucke das Pixel im Hintergrund«).
Die zweiwertige Transparenz kann man als Schmalspurvariante des Alphakanals auffassen. Eine weitere wichtige Einschränkung besteht darin, dass die Maske in PDF immer unmittelbar mit dem Bild verknüpft ist; so ist es nicht möglich, ein Bild zuerst mit
Maske und danach ohne oder mit einer anderen Maske zu verwenden.
Hinweis PDF 1.4 bietet echte Transparenz; diese Funktion wird jedoch von PDFlib bislang nicht unterstützt.
Anzeige und Druck von PDF-Dateien mit Transparenz. Genauso wichtig wie die dem
PDF-Format zugrunde liegenden Einschränkungen in Bezug auf Transparenz sind die
praktischen Auswirkungen in der Viewer-Anwendung. Dabei sind folgende Einschränkungen zu beachten, die sich aber nicht auf Bildmasken beziehen (siehe unten):
> Transparenz funktioniert erst seit PDF 1.3/Acrobat 4 – ältere Viewer ignorieren Transparenzinformationen vollständig und übermalen den Hintergrund bei der Anzeige
und beim Ausdruck.
> Der Ausdruck transparenter Bilder mit PostScript Level 1 oder 2 funktioniert nicht,
auch nicht mit Acrobat 4 (denn Transparenz wird erst in PostScript 3 unterstützt und
lässt sich nicht so einfach emulieren). Acrobat druckt das zugrunde liegende Bild
ohne die Maske.
> Ist ein Bild nach Position maskiert, können Acrobat-4-Viewer die Clipping-Informationen nur bis zu einer bestimmten Bildgröße verarbeiten, andernfalls zeigen sie das
Bild vollständig (unmaskiert) an. Unsere Tests ergaben, dass Acrobat 4 maskierte Bilder nur unter folgender Bedingung korrekt anzeigt:
Breite x Höhe x Anzahl Farbkomponenten/Kanäle < 1024 K
Bilder, die dieses Limit überschreiten, werden unmaskiert angezeigt. Das Limit
scheint für einen normalen PostScript-3-Drucker eher niedriger zu sein. So führt der
Versuch, PDF-Dokumente mit großen maskierten Bildern auszudrucken, zu PostScript-Fehlern.
Transparenz-Unterstützung in PDFlib. PDFlib unterstützt die Maskierung nach Position und die Maskierung nach Farbwert (aber nur über Einzelwerte und keine Bereiche).
PDFlib unterstützt drei Arten der Transparenzinformation: implizite Transparenz, explizite Transparenz und Bildmasken.
77
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. PDFlib versucht, diese Information möglichst
umfassend zu erhalten: Einzelne transparente Farbwerte bleiben erhalten; liegen
mehrere Farbwerte in einem beigefügten Alphakanal vor, wird nur der erste mit einem Alphawert unter 50 Prozent verwendet; eine vollständiger Alphakanal wird ignoriert.
Explizite Transparenz. Im expliziten Fall sind zwei Schritte erforderlich, die jeweils
auch Bildoperationen erfordern. Zuerst muss ein Bild zur späteren Verwendung als
zweiwertige Transparenzmaske vorbereitet werden. Dies lässt sich über die Standardfunktionen für Bilddateien und den zusätzlichen Parameter mask bewerkstelligen. Um
als Maske einsetzbar zu sein, muss das Bild über eine Bittiefe von 1 verfügen, das heißt,
dass sich nur einfarbige Bilder dafür eignen. Die folgende Art von Bildern kann zum Anlegen einer Maske verwendet werden:
> PNG-Bilder
> TIFF-Bilder (nur single-strip)
> Bildrohdaten direkt im Speicher
Überall dort, wo sich in der Maske der Pixelwert o befindet, wird der entsprechende Bereich des maskierten Bildes gezeichnet, während der Wert 1 den Hintergrund durchscheinen lässt. Im zweiten Schritt wird diese Maske auf ein anderes Bild angewandt, das
über eine der Bildfunktionen bezogen wurde:
lMask = oPDF.open_image_file("png", MaskFileName, "mask", 0)
lImage = oPDF.open_image_file(type, FileName, "masked", lMask)
If (lImage <> -1 And lMask <> -1) Then
Else
...
End If
Beachten Sie die unterschiedliche Verwendung des optionalen String-Parameters für
open_image_file( ): mask zur Maskendefinition und masked zur Anwendung einer Maske
auf ein anderes Bild. Der Integer-Parameter bleibt im ersten Schritt ungenutzt, während
er im zweiten Schritt den Maskendeskriptor enthält.
Bild und Maske können unterschiedliche Pixelmaße aufweisen; die Maske wird automatisch auf die Bildgröße skaliert. Maskierte Bilder werden im Kompatibilitätsmodus
für Acrobat 3 nicht unterstützt.
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älle nicht zu vermischen, das heißt, keine Bilder mit transparenten Farbwerten als Maske zu verwenden.
78
Bildmasken. Bildmasken sind Bilder mit einer Bittiefe von 1 (Bitmaps), in den 0-Bits
als transparent behandelt werden. Da heißt, unabhängig vom bereits auf der Seite vorhandenen Inhalt scheint dieser durch die transparenten Bestandteile des Bildes. 1-BitPixel dagegen werden mit der aktuellen Füllfarbe eingefärbt. Die folgenden Arten von
Bildern können als Bildmasken verwendet werden:
> PNG-Bilder
> TIFF-Bilder (»single-strip« oder »multi-strip«)
> Bildrohdaten direkt im Speicher
Bildmasken werden einfach mit dem mask-Parameter geöffnet und auf der Seite platziert, nachdem die gewünschte Füllfarbe gesetzt wurde:
lMask = oPDF.open_image_file("tiff", MaskFileName, "mask", 0)
If (lMask <> -1) Then
oPDF.place_image lMask, 0#, 0#, 1#
End If
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 3.4.6, »Einfärben von Bildern«, Seite 79).
Ignorieren von Transparenz. Manchmal ist es wünschenswert, alle Transparenzinformation 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 Farben schwarz und transparent besitzen. Aus diesem Grund können importierte Bilder
mit feinen Details (zum Beispiel gerasterter Text) hässlich aussehen, wenn die Transparenzinformation ins generierte PDF übernommen wird. Um dieses Problem zu lösen,
kann die automatische Interpretation von Transparenzinformationen in PDFlib beim
Öffnen der Bilddatei mit dem Parameter ignoremask deaktiviert werden:
lImage = oPDF.open_image_file("gif", FileName, "ignoremask", 0)
3.4.6 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 folgenden Formaten möglich:
> PNG
> JPEG
> TIFF (single-strip oder multi-strip)
> GIF (Da GIF-Bilder immer mit RGB-Farbpalette arbeiten, ist ein Einfärben nur sinnvoll, wenn die Palette ausschließlich Graustufenwerte enthält und der Palettenindex
diesen Werten entspricht. PDFlib überprüft dies jedoch nicht.)
Um ein Bild mit einer Schmuckfarbe einzufärben, müssen Sie beim Öffnen des Bildes
den Parameter colorize und ein Handle für die gewünschte Schmuckfarbe übergeben,
welches von makespotcolor( ) zurückgegeben wurde:
oPDF.setcolor "both", "cmyk", 1, .79, 0, 0
spot = oPDF.makespotcolor "Reflex Blue CV", 0
lImage = oPDF.open_image_file("tiff", "image.tif, "colorize", spot)
If (lImage <> -1) Then
79
End If
3.4.7 Mehrseitige Bilddateien
PDFlib unterstützt TIFF-Dateien, die aus mehr als einem Bild bestehen (so genannte
mehrseitige Dateien). Um mehrseitige TIFFs zu verwenden, wird open_image_file( ) mit
weiteren String- und numerischen Parametern aufgerufen:
lImage = oPDF.open_image_file("tiff", FileName, "page", 1)
Der Parameter page zeigt an, dass eine Datei mit mehreren Bildern verwendet werden
soll. Er wird nur bei TIFF-Bildern unterstützt. 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 open_image_file( ) 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 TIFFDatei in ein mehrseitiges PDF-Dokument konvertieren:
Frame = 1
Do
lImage = oPDF.open_image_file("tiff", FileName, "page", Frame)
If (lImage = -1) Then Exit Endif
oPDF.begin_page lWidth, lHeight
oPDF.end_page
Frame = Frame + 1
Loop
3.5 PDF-Import mit PDI
Hinweis Alle in diesem Abschnitt beschriebenen Funktionen setzen die PDF-Importbibliothek PDI voraus, die nicht Bestandteil der PDFlib-Quellcode-Distribution ist. PDI ist zwar in die PDFlibActiveX/COM-Edition integriert, PDFlib-Lizenznehmer müssen dafür aber einen eigenen Lizenzschlüssel erwerben. Weitere Informationen über den Erwerb von PDI finden Sie auf unseren
Webseiten.
3.5.1 PDI-Funktionen und -Anwendungen
Wird PDFlib um die optionale PDF-Importbibliothek PDI ergänzt, können mit allen unterstü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 platzieren sie auf einer Ausgabeseite. Dabei können Sie sie mit PDFlib-Transformationsfunktionen 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:
80
> eine PDF-Hintergrundseite platzieren und mit dynamisch generierten Daten füllen
(zum Beispiel Serienbriefe, personalisierte PDF-Dokumente im Web oder Ausfüllen
von Formularen)
> 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
> 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
3.5.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
Hypertextfunktionen (wie zum Beispiel Sound, Movies, eingebettete Dateien, Hypertextverknüpfungen, Formularfelder, Lesezeichen, Piktogramme oder Notizen). Solche
Hypertextfunktionen lassen sich mit den entsprechenden PDFlib-Funktionen generieren. Auch können Sie einzelne Elemente der importierten Seite nicht in PDFlib-Funktionen weiterverwenden. So lassen sich Schriften aus importierten Dokumenten nicht für
andere Inhalte benutzen, da alle benötigten Schriften in PDFlib konfiguriert sein müssen. Enthalten mehrere importierte Dokumente eingebettete Fontdaten derselben
Schrift, so werden diese 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 offenhalten, 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
es zum Beispiel Farbprofile, so werden diese auch in die generierte Ausgabe übernommen.
PDFlib platziert importierte PDF-Seiten auf der Ausgabeseite mittels der TemplateFunktion. Da einige PDF-Programme von Drittanbietern die Template-Funktion nicht
korrekt unterstützen, kann es dabei diverse Einschränkungen geben (siehe Abschnitt
3.2.4, »Templates«, Seite 44).
Von PDFlib generierte Ausgabe, die importierte Seiten aus anderen PDF-Dokumenten 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 vorhandenen PDF-Dokumenten ist mit sehr einfach strukturiertem Code möglich. Das folgende Fragment öffnet eine vorhandene Dokumentseite und kopiert den Seiteninhalt auf
eine neue Seite des PDF-Ausgabedokuments (das vorher geöffnet werden muss):
Dim
Dim
Dim
doc, page, pageno;
sheetwidth, sheetheight;
filename
81
...
pageno = 1
doc = oPDF.open_pdi(filename, "", 0)
If (doc = -1) Then
MsgBox "Eingabedatei kann nicht geöffnet werden!"
End
End If
page = oPDF.open_pdi_page(doc, pageno, "")
if (page = -1) Then
MsgBox "Seite in Eingabedatei kann nicht geöffnet werden!"
End
End If
sheetwidth = oPDF.get_pdi_value("width", doc, page, 0)
sheetheight = oPDF.get_pdi_value("height", doc, page, 0)
oPDF.begin_page sheetwidth, sheetheight
oPDF.place_pdi_page page, 0, 0, 1, 1
oPDF.close_pdi_page page
...mit PDFlib-Funktionen weiteren Seiteninhalt hinzufügen...
oPDF.end_page
Die PDFlib-Distribution enthält PDI-Beispiele für alle unterstützten Sprachbindungen,
die verschiedene Einsatzmöglichkeiten der PDI-Funktionen demonstrieren:
> Das Personalization-Beispiel extrahiert eine Seite aus einem vorhandenen PDFDokument und platziert zusätzlichen Text auf der Seite.
> Das Quickreference-Beispiel extrahiert mehrere Seiten aus einem vorhandenen PDFDokument, verkleinert sie und platziert sie in der Ausgabe auf einem einzigen Blatt.
> Das Imposition-Beispiel (das nur in C verfügbar ist) stellt eine Verallgemeinerung
des Quickreference-Beispiels dar. Es verarbeitet eine beliebige Anzahl von PDF-Dokumenten und platziert n x m Seiten auf einem Blatt. Außerdem wird um die verkleinerten Seiten ein Rahmen gezogen.
Abmessungen importierter PDF-Seiten. Importierte PDF-Seiten werden im Prinzip wie
importierte Rasterbilder behandelt und können mit place_pdi_page( ) auf der Ausgabeseite platziert werden. Die PDI-Bibliothek importiert die Seite standardmäßig genau so,
wie sie in Acrobat angezeigt wird, insbesondere mit folgenden Eigenschaften:
> 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, »Begrenzungen für Seiten und Koordinaten«, Seite 42);
> Eine eventuell auf die Seite angewandte Drehung bleibt erhalten.
Alternativ dazu können Sie PDI mit dem Parameter pdiusebox explizit anweisen, zur Ermittlung 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 4.17).
82
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 4.16
und Tabelle 4.17 aufgeführt. Diese Eigenschaften können bei Entscheidungen über die
Platzierung importierter PDF-Seiten auf der Ausgabeseite hilfreich sein. Auch der in Abschnitt 3.4.2, »Häufig benötigte Codefragmente für Rasterbilder«, Seite 74, beschriebene
Algorithmus kann zur Skalierung importierter PDF-Seiten herangezogen werden.
Umgang mit Dateien im Format Acrobat 5/PDF 1.4. PDI ist vollständig kompatibel zu
Dateien im Format PDF 1.4, die mit Acrobat 5 generiert wurden. Sie sollten jedoch Folgendes beachten: Importierte PDF-Dokumente dürfen keine höhere Versionsnummer
als die generierte Ausgabe aufweisen. Da der Ausgabemodus in PDFlib 4 standardmäßig
zu Acrobat 4/PDF 1.3 kompatibel ist, werden importierte Dateien im Format PDF 1.4 zunächst abgelehnt. Dieses Verhalten kann durch Änderung der Versionsnummer der von
PDFlib generierten PDF-Ausgabe wie folgt verhindert werden:
oPDF.set_parameter "compatibility", "1.4"
Dies bewirkt PDF-Ausgabe, die zu Acrobat 5/PDF 1.4 kompatibel ist, was wiederum Voraussetzung für den Import von Dateien im Format PDF 1.4. ist.
3.5.3 Importierbare PDF-Dokumente
PDI verarbeitet in der Regel problemlos alle Arten von PDF-Dokumenten, die sich auch
in Acrobat öffnen lassen, völlig unabhängig von der PDF-Versionsnummer oder den im
Dokument verwendeten Funktionen. Nur selten tritt der Fall auf, dass PDI ein ganzes
PDF-Dokument oder eine einzelne Seite im Dokument zurückweist. Je nach Einstellung
des Parameters pdiwarning wird bei nicht akzeptierten PDF-Dateien entweder einfach
ein Fehlercode zurückgegeben oder es gibt eine nicht fatale Exception mit einer genauen Fehlerbeschreibung. Folgende Arten von PDF-Dokumenten können mit PDI nicht
importiert werden:
> PDF-Dokumente, die eine höhere PDF-Versionsnummer aufweisen als die gerade zu
generierende PDF-Ausgabe. Der Grund besteht darin, dass PDFlib nach dem Import
eines solchen Dokuments nicht mehr gewährleisten könnte, dass die Ausgabe auch
tasächlich der geforderten PDF-Version entspricht. Lösung: Setzen Sie die Version
der PDF-Ausgabe mit dem Parameter compatibility entsprechend herauf.
> Dateien mit beschädigter Querverweistabelle. Sie erkennen solche Dateien 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.
> Verschlüsselte PDF-Dokumente (das heißt Sicherheitseinstellungen mit oder ohne
Benutzerpasswort). Lösung: Entfernen Sie alle Sicherheitseinstellungen in Acrobat
und speichern Sie das Dokument erneut. Dazu benötigen Sie natürlich das Kennwort
für das Dokument.
> Da in PDFlib/PDI der LZW-Algorithmus nicht implementiert ist, werden PDF-Seiten,
die LZW-Kompression verwenden (genauer gesagt, mit LZW komprimierte Seiten
mit mehreren Content-Streams), abgelehnt (unsupported filter). Lösung: Speichern Sie
das Dokument in Acrobat ab 4.0, wobei Sie die entsprechende Option aktivieren (in
Acrobat 5 Bearbeiten, Grundeinstellungen, Allgemein, Optionen, Speichern unter optimiert
für schnelle Web-Anzeige). Beachten Sie, dass Dateien mit LZW-Kompression ab Acrobat Version 4.0 nicht mehr erzeugt werden, sondern nur von Acrobat 3 unter be-
83
stimmten Umständen und von Acrobat Capture 2. Aus diesem Grund werden Sie mit
diesem Problem aller Wahrscheinlichkeit nach nicht konfrontiert werden. Wenn Sie
eine sehr große Anzahl solcher Dokumente besitzen, die konvertiert werden müssen,
sollten Sie sich die Stapelverarbeitung von Acrobat näher betrachten.
3.5.4 PDF-Import, Templates und Vererbung des Grafik- und
Textzustands
Grafikparameter können auf einer Seite explizit gesetzt oder in einem Template oder einer importierten PDF-Seite eingestellt sein. Damit erhebt sich die Frage, in welcher Weise grafische Eigenschaften (der so genannte Grafikzustand) weitergegeben (vererbt)
werden. Wenn die aktuelle Farbe beispielsweise auf Blau gesetzt ist und das Template
oder die importierte Seite ein Objekt zeichnet, sollte das Objekt dann ebenfalls blau
sein? Auf den ersten Blick scheint das eine einfache Angelegenheit zu sein. Leider verkompliziert sich die Sache durch Fehler im Druckertreiber von Acrobat, die bewirken
können, dass sich Druckausgabe und Bildschirmanzeige des PDF-Dokuments unterscheiden. Aus diesem Grund verhält sich PDFlib wie folgt:
> Ist der Parameter inheritgstate auf true gesetzt, können Templates und importierte
PDF-Seiten Text- oder Grafikparameter von der importierenden Seite erben.
> Ist inheritgstate auf false gesetzt, stellt PDFlib sicher, dass Templates und importierte
PDF-Seiten vom Inhalt der umgebenden Seite unabhängig sind und ihr Aussehen
nicht ändern. Dazu initialisiert PDFlib alle relevanten Text- und Grafikparameter in
geeigneter Weise, bevor das Template platziert wird.
Aus Kompatibilitätsgründen hat der Parameter inheritgstate den Standardwert true. Die
Auswirkungen sind aber so unberechenbar und verwirrend, dass wir allen PDFlib-Benutzern dringend von der damit verbundenen Vererbung des Grafikstatus abraten.
Hinweis In zukünftigen Versionen von PDFlib wird der Parameter inheritgstate nicht mehr unterstützt
und prinzipiell das Verhalten für inheritgstate gleich »false« implementiert.
84
4 PDFlib- und PDI-API-Referenz
In der PDFlib-API-Referenz werden alle unterstützten PDFlib-Funktionen beschrieben.
4.1 Datentypen, Namenskonventionen und
Geltungsbereiche
Datentypen und PDFlib. Im Prinzip greifen alle ActiveX-fähigen Entwicklungsumgebungen in derselben Art auf PDFlib-Routinen zu. In einigen Fällen unterscheiden sich
jedoch die Datentypen für PDFlib-Funktionsparameter. Wie Tabelle 4.1 zeigt, können
insbesondere die Datentypen für Strings und Binärdaten leicht abweichen.
Tabelle 4.1 Datentypen in den verschiedenen Sprachbindungen
Entwicklungsumgebung
String-Datentyp
Binärdatentyp
ActiveX allgemein
BSTR (String)
Variant vom Typ VT_ARRAY | VT_UI1 1
Delphi
String (für 8-Bit-Zeichensätze) oder
WideString (für Unicode)
OleVariant
1. Mit anderen Worten ein Varianten-Array vorzeichenloser Bytes.
Geltungsbereich von Funktionen. Bei den meisten PDFlib-Funktionen sind bestimmte
Regeln hinsichtlich der Reihenfolge und Verschachtelung zu beachten, die sich aus ihrem Beitrag zum zu generierenden Dokument ergeben. Die meisten dieser Regeln sind
ziemlich offensichtlich. So müssen Sie eine Seite natürlich erst einmal öffnen, bevor Sie
sie wieder schließen können. Genauso dürfen Funktionen zum Öffnen und Schließen
null
object
document
page
page
path
path
page
...
pattern
font
path
glyph
page
path
page
path
gstate
page
...
path
template
Abb. 4.1
Verhältnis der
Geltungsbereiche zueinander
page
path
template
document
page
pattern
font
path
glyph
gstate
...
4.1 Datentypen, Namenskonventionen und Geltungsbereiche
85
eines PDF-Dokuments immer nur paarweise auftreten. Um die korrekte Reihenfolge
von Funktionen, die von Client-Programmen verwendet werden, zu definieren und zu
verifizieren, arbeitet PDFlib mit Geltungsbereichen, die streng einzuhalten sind. Zu jeder Funktion wird deshalb auch ihr Geltungsbereich angeführt; Tabelle 4.2 definiert die
verschiedenen Geltungsbereiche, während Abbildung 4.1 ihre Zusammenhänge veranschaulicht. PDFlib löst eine Exception aus, wenn eine Funktion außerhalb ihres zulässigen Geltungsbereichs aufgerufen wird. Der aktuelle Geltungsbereich kann mit dem Parameter scope abgefragt werden.
Tabelle 4.2 Geltungsbereiche für Funktionen
Name
Definition
path
beginnt mit moveto( ), circle( ), arc( ), arcn( ) oder rect( ) und endet mit einer der Funktionen aus
Abschnitt 4.4.5, »Zeichnen und Beschneiden von Pfaden«, Seite 104
page
zwischen begin_page( ) und end_page( ), aber außerhalb von path
template
zwischen begin_template( ) und end_template( ), aber außerhalb von path
pattern
zwischen begin_pattern( ) und end_pattern( ), aber außerhalb von path
document
zwischen open_file( ) und close( ), aber außerhalb von page, template und pattern
object
solange ein PDFlib-Objekt vorhanden ist, aber außerhalb von document
4.2 Allgemeine Funktionen
4.2.1 Setup
Tabelle 4.3 enthält eine Übersicht aller für diesen Abschnitt relevanten Parameter und
Werte.
Tabelle 4.3 Parameter und Werte für Setup-Funktionen
Funktion
Schlüssel
Erklärung
set_parameter compatibility Setzt den PDFlib-Kompatibilitätsmodus auf einen der Strings »1.2«, »1.3« oder
»1.4« für Acrobat 3, 4 oder 5. Standardmäßig wird »1.3« verwendet (siehe
Abschnitt 1.3, »Ausgabe und Kompatibilität von PDFlib«, Seite 12). Dieser
Parameter muss vor dem ersten Aufruf von open_*( ) gesetzt werden.
Geltungsbereich: object.
86
set_parameter prefix
Namenspräfix für die Ressourcedatei in einer UPR-Datei (siehe Abschnitt 3.3.7,
»Ressourcekonfiguration und die UPR-Ressourcedatei«, Seite 57). Das Präfix darf
nur einmal gesetzt werden. Es enthält einen Schrägstrich sowie einen Pfadnamen,
der wiederum mit einem Schrägstrich beginnen kann. Geltungsbereich: object.
set_parameter resourcefile
Relativer oder absoluter Name der von PDFlib verwendeten UPR-Ressourcedatei.
Diese wird geladen, sobald das nächste Mal versucht wird, auf Ressourcen
zuzugreifen. Der Ressourcedateiname darf nur einmal festgelegt werden. Der
Aufruf sollte vor der ersten Seite erfolgen. Geltungsbereich: object.
set_parameter serial
Setzt die Seriennummer von PDFlib und/oder PDI (siehe Abschnitt 2.2.2,
»Installation der ActiveX-Edition von PDFlib«, Seite 17). Diese kann nur einmal
festgelegt werden, und zwar vor dem ersten Aufruf von begin_page( ).
Geltungsbereich: object.
set_parameter warning
Aktiviert oder deaktiviert die Ausgabe von Warnungen (nicht-fatale Exceptions).
Mögliche Werte sind true und false, der Standardwert ist true. Geltungsbereich:
beliebig.
Kapitel 4: PDFlib- und PDI-API-Referenz (ActiveX/COM- und .NET-Edition)
Tabelle 4.3 Parameter und Werte für Setup-Funktionen
Funktion
Schlüssel
Erklärung
set_value
compress
Setzt den Kompressionsparameter auf einen Wert zwischen 0 und 9. Dieser
Parameter hat keinen Einfluss auf vorkomprimierte Rasterbilddaten, die im PassThrough-Modus bearbeitet werden. Geltungsbereich: beliebig.
0
keine Kompression
1
maximale Geschwindigkeit
6
Standardwert
9
maximale Kompression
get_value
major
minor
revision
Gibt die Major-Versionsnummer, die Minor-Versionsnummer oder die
Revisionsnummer von PDFlib zurück. Geltungsbereich: beliebig, null.
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, null.
get_parameter scope
Gibt den Namen des aktuellen Geltungsbereichs zurück. Geltungsbereich:
beliebig.
4.2.2 Dokument und Seite
Werte. In Abschnitt 4.8.1, »Aktion und Modus beim Öffnen des Dokuments«, Seite 118,
finden Sie weitere relevante Parameter.
Tabelle 4.4 Parameter und Werte für Dokument- und Seitenfunktionen
Funktion
key
Erklärung
set_value
pagewidth
pageheight
Ändert die Größe der aktuellen Seite. Geltungsbereich: page.
get_value
pagewidth
pageheight
Ermittelt die Größe der aktuellen Seite. Geltungsbereich: page.
set_value
CropBox,
BleedBox,
ArtBox,
TrimBox
Ändert eine der Größenangaben der aktuellen Seite. Diese Parameter dürfen nur
innerhalb einer Seitenbeschreibung verwendet werden. Auf den Parameternamen
muss ein Schrägstrich ’/’ sowie llx, lly, urx oder ury folgen, zum Beispiel: CropBox/
llx (siehe auch Abschnitt 3.2.2, »Begrenzungen für Seiten und Koordinaten«, Seite
42). Geltungsbereich: page.
Function open_file(filename As String) As Long
Erzeugt eine neue PDF-Datei mit dem übergebenen Dateinamen.
filename Name der zu generierenden PDF-Ausgabedatei. Ist filename leer, wird das
PDF-Dokument direkt im Arbeitsspeicher und nicht auf der Festplatte abgelegt. In diesem Fall muss das Ergebnis vom Client mit der Funktion PDF_get_buffer( ) abgeholt werden. PDF_open_file( ) ist dann immer erfolgreich und gibt niemals den Fehlercode -1 zurück.
Rückgabe -1 im Fehlerfall, sonst 1.
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 abgeschlossen ist.
87
Gültigkeit object; mit dieser Funktion beginnt der Geltungsbereich document, sofern die Datei
erfolgreich geöffnet werden konnte. Diese Funktion muss immer paarweise mit close( )
auftreten.
Function get_buffer( )
Holt den Inhalt des PDF-Ausgabepuffers. Das Ergebnis muss vom Client verwendet werden, bevor eine andere PDFlib-Funktion aufgerufen wird.
Rückgabe Ein Puffer mit binären PDF-Daten zur Weiterverarbeitung durch den Client. Die meisten
ActiveX/COM-Clients speichern den Pufferinhalt in einem Variant-Typ. Der zurückgegebene Puffer kann bis zum Ende des umgebenden Geltungsbereichs object 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 generierten PDF-Daten zurück. Wird sie nach PDF_close( ) aufgerufen, dann gibt sie den
Rest des PDF-Dokuments zurück. Wird diese Funktion nur ein einziges Mal und zwar
nach PDF_close( ) aufgerufen, enthält der Rückgabepuffer garantiert das vollständige
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-Werte vorbereitet sein.
Gültigkeit object, document (mit anderen Worten: nach end_page( ) und bevor begin_page( ), oder
nach close( ) und vor delete( ). Diese Funktion darf nur verwendet werden, wenn ein
leerer Dateiname an open_file( ) übergeben wurde.
Sub close( )
Schließt die generierte PDF-Datei und gibt alle dokumentspezifischen Ressourcen frei.
Details Diese Funktion beendet das generierte PDF-Dokument, gibt alle dokumentspezifischen
Ressourcen frei und schließt die Ausgabedatei, sofern das Dokument mit PDF_open_
file( ) geöffnet wurde. Diese Funktion muss nach Abschluss der Seitengenerierung auf
jeden Fall aufgerufen werden, unabhängig davon, auf welche Art das PDF-Dokument geöffnet wurde.
Wurde das Dokument direkt im Speicher erzeugt (und nicht in einer Datei), bleibt
der Dokumentpuffer auch nach dem Aufruf dieser Funktion erhalten (damit sein Inhalt
mit PDF_get_buffer( ) abgeholt werden kann). Er wird beim nächsten Aufruf von PDF_
open( ) freigegeben oder wenn das PDFlib-Objekt ungültig wird.
Gültigkeit document; mit dieser Funktion wird der Geltungsbereich document beendet; diese
Funktion muss immer paarweise mit open( ) auftreten.
Sub begin_page(width As Single, height As Single)
Fügt eine neue Seite zum Dokument hinzu.
width, height Die Parameter width und height geben die Größe der neuen Seite in
Punkt an. Die Beschränkungen der Seitengröße in Acrobat werden in Abschnitt 3.2.1,
»Koordinatensysteme«, Seite 40, beschrieben. Eine Liste üblicher Seitenformate finden
88
Sie in Tabelle 4.26 in Abschnitt 4.9, »Seitenformate«, Seite 126. Die Seitengröße kann
nach dem Aufruf von begin_page( ) mit den Parametern pagewidth und pageheight geändert werden. Um Seiten im Querformat zu erstellen, muss width > height sein. PDFlib
verwendet width und height zur Erzeugung der MediaBox der Seite. Mit verschiedenen
anderen Parametern lassen sich weitere Größenangaben im PDF-Dokument festlegen
(siehe Tabelle 4.3).
Gültigkeit document; mit dieser Funktion beginnt der Geltungsbereich page; diese Funktion muss
immer paarweise mit PDF_end_page( ) auftreten.
Parameter pagewidth, pageheight, CropBox, BleedBox, ArtBox, TrimBox
Sub end_page( )
Beendet die Seite.
Details Diese Funktion muss zur Beendigung einer Seitenbeschreibung benutzt werden.
Gültigkeit page; mit dieser Funktion endet der Geltungsbereich page; diese Funktion muss immer
paarweise mit begin_page( ) auftreten.
4.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 Setzen und Ermitteln numerischer und String-Parameter stehen vier Funktionen bereit. Bei allen Parametern
(Schlüssel wie Werte) wird zwischen Groß- und Kleinschreibung unterschieden. Bei jeder Kategorie von Funktionen werden auch die jeweils relevanten Parameter beschrieben.
Function get_value(key As String, modifier As Single) As Single
Ermittelt den Wert eines numerischen PDFlib-Parameters.
key
Name des abzufragenden Parameters.
modifier Optionaler Modifizierer, der auf den Parameter anzuwenden ist. Ob ein Modifizierer erforderlich ist und worauf er sich gegebenenfalls bezieht, wird in den verschiedenen 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 get_pdi_value( )
Sub set_value(key As String, value As Single)
Setzt den Wert eines numerischen PDFlib-Parameters.
key
value
Name des zu setzenden Parameters.
Neuer Wert des zu setzenden Parameters.
89
Function get_parameter(key As String, modifier As Single) As String
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 Modifizierer erforderlich ist und worauf er sich gegebenenfalls bezieht, wird in den verschiedenen 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 umgebenden Geltungsbereichs document verwendet werden.
Siehe auch PDF_get_pdi_parameter( )
Sub set_parameter(key As String, value As String)
Setzt einen PDFlib-Parameter vom Typ String.
key
value
Name des zu setzenden Parameters.
Neuer Wert des zu setzenden Parameters.
4.3 Textfunktionen
4.3.1 Fontbehandlung
Werte.
Tabelle 4.5 Parameter und Werte für Fontfunktionen (siehe Abschnitt 4.2.3, »Parameterbehandlung«, Seite 89)
Funktion
90
Schlüssel
Erklärung
set_parameter FontAFM
FontPFM
FontOutline
Encoding
Wie die jeweilige Zeile in der entsprechenden Kategorie der UPR-Ressourcedatei
(siehe Abschnitt 3.3.7, »Ressourcekonfiguration und die UPR-Ressourcedatei«, Seite
57). Durch mehrere Aufrufe erhält die interne Liste neue Einträge (siehe auch
prefix und resourcefile in Tabelle 4.3). Geltungsbereich: beliebig.
get_value
Gibt den Identifier des aktuellen Fonts zurück, der mit setfont( ) gesetzt worden
sein muss. Geltungsbereich: page, pattern, template.
font
get_parameter fontname
Name des aktuellen Fonts, der mit setfont( ) gesetzt worden sein muss.
Geltungsbereich: page, pattern, template.
get_parameter fontencoding
Name des Zeichensatzes oder der CMap, die für die aktuelle Schrift verwendet
wird. Der Font muss mit setfont( ) gesetzt worden sein. Geltungsbereich: page,
pattern, template.
get_value
Gibt die Größe des aktuellen Fonts zurück, der mit setfont( ) gesetzt worden sein
muss. Geltungsbereich: page, pattern, template.
fontsize
Tabelle 4.5 Parameter und Werte für Fontfunktionen (siehe Abschnitt 4.2.3, »Parameterbehandlung«, Seite 89)
Funktion
Schlüssel
Erklärung
get_value
capheight
ascender
descender
Gibt Metrikdaten für den durch den Modifizierer bezeichneten Font zurück.
Weitere Informationen finden Sie in Abschnitt 3.3.10, »Textmetrik, Textvarianten
und Formatierung in ein Rechteck«, Seite 67. 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 gleich false, gibt findfont( ) -1 zurück (statt eine Exception auszulösen),
wenn die Font/Zeichensatz-Kombination nicht geladen werden kann.
Standardwert ist true. Geltungsbereich: beliebig.
Function findfont(fontname As String, encoding As String, options As Long) As Long
Sucht nach einer Schrift und bereitet sie zur späteren Verwendung vor.
fontname
Name der Schrift, wie er in PDFlib konfiguriert ist.
encoding Bei 8-Bit-Schriften bezeichnet encoding einen der Zeichensätze builtin,
macroman, winansi, ebcdic oder host (siehe Abschnitt 3.3.2, »In PDFlib integrierte 8-BitZeichensätze«, Seite 46) oder den Namen eines externen von PDFlib gelieferten oder benutzerdefinierten Zeichensatzes (siehe Abschnitt 3.3.3, »Benutzerdefinierte 8-Bit-Zeichensätze und Codepages«, Seite 48). Beachten Sie, dass Sie die Metrikdaten für eine
Schrift benötigen, um mit beliebigen Zeichensätzen arbeiten zu können (siehe Abschnitt 3.3.6, »PostScript-, TrueType- und OpenType-Schriften«, Seite 53).
Alternativ dazu kann encoding den Namen einer der integrierten CMaps enthalten,
sofern fontname einen CID-Schrift bezeichnet (siehe Abschnitt 3.3.8, »Japanischer, chinesischer und koreanischer Text«, Seite 60). In diesem Fall sind keine Metrikdaten erforderlich. Bei fontname sowie encoding wird zwischen Groß- und Kleinschreibung unterschieden.
options Steuert die Schriftverarbeitung. Wird eine Schrift eingebettet, muss neben
den Metrikdaten auch die Fontdatei verfügbar sein (bei TrueType- und OpenTypeSchriften sind die Metrikdaten bereits in der Fontdatei enthalten). Die tatsächliche
Schriftdefinition wird dann in die PDF-Ausgabe übernommen. Beim Aufruf dieser
Funktion wird lediglich überprüft, ob die Fontdatei existiert. Sie wird erst später benutzt, da die Schrifteinbettung erst am Ende der generierten PDF-Datei erfolgt. Wird
eine Schrift nicht eingebettet, dann werden nur allgemeine Fontinformationen in die
PDF-Ausgabe aufgenommen.
Tabelle 4.6 zeigt alle möglichen Werte für den Parameter options.
Tabelle 4.6 Werte für den Parameter options
Wert
Schrifteinbettung
Einlesen von Kerning-Daten, falls vorhanden
0
nein
nein
1
ja
nein
Der Parameter options muss bei CID-Schriften auf 0 gesetzt sein.
Rückgabe Fonthandle zur späteren Verwendung in setfont( ). Das Verhalten dieser Funktion ändert sich, wenn der Parameter fontwarning auf false gesetzt wird. findfont( ) gibt dann
den Fehlercode -1 zurück, statt eine Exception auszulösen, wenn die angeforderte Font-
4.3 Textfunktionen
91
Zeichensatz-Kombination nicht geladen werden kann. Bei nicht korrekten Parametern
wird aber auch weiterhin eine Exception ausgelöst.
Der zurückgegebene Wert – das Fonthandle – hat für den Benutzer keinerlei inhaltliche Bedeutung. Er dient lediglich als Argument für setfont( ) und verwandte Funktionen.
Beim Anfordern der gleichen Font-Zeichensatzkombination in verschiedenen Dokumenten können unterschiedliche Fonthandles zurückgegeben werden.
Details Diese Funktion bereitet eine Schrift zur späteren Verwendung in setfont( ) vor. Die Metrikdaten werden aus dem Arbeitsspeicher oder aus einer externen Metrikdatei geladen.
Eine Exception vom Typ PDF_RuntimeError wird ausgelöst, wenn die angeforderte FontZeichensatz-Kombination 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). Anderenfalls kann der von dieser Funktion zurückgegebene Wert als Fontargument in weiteren Funktionen zur Schriftbehandlung verwendet werden.
CID-Schriften werden im Kompatibilitätsmodus für Acrobat 3 nicht unterstützt.
Gültigkeit document, page, pattern, template
Parameter Siehe Tabelle 4.5.
Sub setfont(font As Long, fontsize As Single)
Setzt die aktuelle Schrift in der festgelegten Größe.
font
Fonthandle, das von findfont( ) zurückgegeben wurde.
fontsize Größe der Schrift, gemessen in Einheiten des aktuellen benutzerdefinierten
Koordinatensystems.
Details Die Schrift muss auf jeder Seite erneut gesetzt werden, und zwar vor dem Zeichnen von
jeglichem Text. 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
Parameter Siehe Tabelle 4.5. Die Funktion setzt den Parameter leading für den Zeilenabstand auf
fontsize.
4.3.2 Textausgabe
Hinweis Jeder Text, der an die in diesem Abschnitt beschriebenen Funktionen übergeben wird, muss zu
dem Zeichensatz passen, der mit findfont( ) selektiert wurde. Dies gilt für 8-Bit-Text ebenso wie
für Unicode oder andere über eine CMap festgelegte Zeichensätze.
Werte.
Sub set_text_pos(x As Single, y As Single)
Setzt die aktuelle Textposition.
x, y
92
Aktuelle Textposition, die gesetzt werden soll.
Tabelle 4.7 Parameter und Werte für Textfunktionen (siehe Abschnitt 4.2.3, »Parameterbehandlung«, Seite 89)
Funktion
Schlüssel
Erklärung
set_value
get_value
leading
Setzt oder ermittelt den Zeilenabstand (leading), der als Abstand zwischen den
Grundlinien aufeinanderfolgender Textzeilen definiert ist. Der Zeilenabstand wird
in continue_text( ) verwendet und auf die Schriftgröße gesetzt, wenn eine neue
Schrift mit setfont( ) festgelegt wird. Wird der Zeilenabstand mit der Schriftgröße
gleichgesetzt, stoßen die Zeilen fast aneinander. Ober- und Unterlängen
aufeinanderfolgender Zeilen überlappen aber in der Regel nicht. Geltungsbereich:
page, pattern, template.
set_value
get_value
textrise
Setzt oder ermittelt den Parameter für den vertikalen Textversatz (text rise). Dieser
legt den 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.
set_value
get_value
textrendering Setzt oder ermittelt den aktuellen Darstellungsmodus für Text (text rendering
mode). Dieser Parameter kann einen der Werte in Tabelle 3.9 haben. Am Anfang
jeder Seite wird er auf den Standardwert 0 gesetzt (= ganzflächige Füllung).
set_value
get_value
horizscaling
Setzt oder ermittelt die Skalierung von Text (horizontal text scaling). Diese wird in
Prozent angegeben und muss größer als 0 sein. Der Parameter legt anhand eines
Prozentwerts 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, document.
set_value
get_value
charspacing
Setzt oder ermittelt den Zeichenabstand, das heißt, wie stark sich die aktuelle
Position nach der Platzierung eines einzelnen Zeichens in einem String ändert. Der
Zeichenabstand wird in Einheiten des aktuellen benutzerdefinierten Koordinatensystems angegeben. Am Anfang und am Ende jeder Seite wird er auf den Standardwert 0 zurückgesetzt. Um einen weiteren Zeichenabstand zu erreichen,
verwenden Sie positive Werte im horizontalen Ausgabemodus und negative
Werte im vertikalen Ausgabemodus. Geltungsbereich: page, pattern, template,
document.
set_value
get_value
wordspacing Setzt oder ermittelt den Wortabstand, das heisst, wie stark sich die aktuelle
Position nach der Platzierung eines Wortes in einer Textzeile ändert. Anders
ausgedrückt, wird die aktuelle Position nach jedem ASCII-Leerzeichen (&H20)
horizontal verschoben. Da Schriften mit Multibyte-Zeichensätzen über kein ASCIILeerzeichen verfügen, werden sie vom hier definierten Wortabstand nicht beeinflusst. 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, document.
get_value
textx
texty
Ermittelt die x- bzw. y-Koordinate der aktuellen Textposition (nicht für CID-Fonts).
set_parameter underline
get_parameter overline
strikeout
Setzt oder ermittelt den aktuellen Modus für Unterstreichen, Überstreichen bzw.
Durchstreichen, der bis zu einer expliziten Änderung beibehalten wird. Diese Modi
können unabhängig voneinander eingestellt werden. Am Anfang jeder Seite
werden sie auf false zurückgesetzt (siehe Abschnitt 3.3.10, »Textmetrik,
Textvarianten und Formatierung in ein Rechteck«, Seite 67). Geltungsbereich:
page, pattern, template.
true
Text unterstreichen/überstreichen/durchstreichen (nicht für CID-Fonts)
false
Text nicht unterstreichen/überstreichen/durchstreichen
set_parameter nativeunicode
Ist dieser Parameter auf true gesetzt, wird Unicode-Textverarbeitung mit UCS-2Zeichensatz für Sprachbindungen mit Unicode-Unterstützung aktiviert; bei false
ist sie deaktivert. Standardwert ist false (siehe Abschnitt 3.3.9, »UnicodeUnterstützung«, Seite 65). Geltungsbereich: beliebig.
4.3 Textfunktionen
93
Details Zu Beginn jeder Seite wird die Textposition auf den Standardwert (0, 0) gesetzt. Der aktuelle Punkt für die Grafikausgabe und die aktuelle Textposition werden getrennt verwaltet.
Sub show(text As String)
Gibt Text in der aktuellen Schrift und Größe an der aktuellen Textposition aus.
text
Auszugebender Text.
Details Vor dieser Funktion müssen sowohl die Schrift (mit setfont( )) als auch die aktuelle Textposition (mit set_text_pos( ) oder einer anderen Textausgabefunktion) gesetzt worden
sein. Die aktuelle Textposition wird an das Ende des ausgegebenen Texts verschoben.
Sub show_xy(text As String, x As Single, y As Single)
Gibt text mit der aktuellen Schrift an Position (x, y) aus.
text
Auszugebender Text.
x,y Position im benutzerdefinierten Koordinatensystem, in dem der Text ausgegeben
wird.
Details Die Schrift muss zuvor mit setfont( ) eingestellt worden sein. Die aktuelle Textposition
wird ans Ende des ausgegebenen Texts bewegt.
Sub continue_text(text As String)
Gibt Text in der nächsten Zeile aus.
text Auszugebender Text. Wird ein Leerstring übergeben, wird die Textposition auf jedem Fall in die nächste Zeile bewegt.
Details Die Textpositionierung und der Zeilenabstand werden durch den Parameter leading sowie den letzten Aufruf von PDF_show_xy( ) oder PDF_set_text_pos( ) bestimmt. Diese
Funktion kann auch nach PDF_show_boxed( ) ausgeführt werden, wenn diese mit mode =
left oder justify aufgerufen wurde. Die aktuelle Position wird ans Ende des auszugebenden Texts bewegt.
Gültigkeit page, pattern, template; diese Funktion sollte im vertikalen Textausgabemodus nicht
verwendet werden.
94
Function show_boxed(text As String, x As Single, y As Single, width As Single,
height As Single, mode As String, feature As String) As Long
Formatiert Text in ein Rechteck unter Berücksichtigung des angegebenen Formatierungsmodus.
text
ten.
Text, der in das Rechteck formatiert werden soll. Er darf keine Nullzeichen enthal-
x, y Koordinaten einer Ecke des Rechtecks oder Koordinaten des Ausrichtungspunkts,
falls width = 0 und height = 0.
width, height
Größe des Rechtecks oder 0 bei Formatierung einer einzelnen Zeile.
mode mode selektiert den Modus für die horizontale Ausrichtung. Ist width = 0 und
height = 0, kann mode einen der Werte left, right oder center annehmen. Der Text wird
dann entsprechend der gewählten Ausrichtung ausgehend vom Punkt (x, y) formatiert,
wobei y die Position der Grundlinie angibt. In diesem Modus überprüft die Funktion
nicht, ob der Text aufgrund der übergebenen Parameterwerte am Seitenrand abgeschnitten wird. Es findet keinerlei Zeilenumbruch statt und es wird immer der Wert o
zurückgegeben.
Sind width oder height von 0 verschieden, kann mode einen der Werte left, right,
center, justify oder fulljustify annehmen. Der übergebene Text wird in ein Rechteck formatiert, dessen linke untere Ecke durch (x, y) gegeben ist (siehe auch Koordinaten mit
dem Ursprung in der linken oberen Ecke in Abschnitt 3.2.1, »Koordinatensysteme«, Seite
40) und dessen Abmessungen in width und height übergeben werden. Passt der Text
nicht in eine Zeile, wird der Text mit einem einfachen Algorithmus in die nächste verfügbare Zeile umgebrochen, wobei der Zeilenwechsel möglichst bei vorhandenen Leeroder Tabulatorzeichen erfolgt. Die Modi left, right und center bestimmen die Ausrichtung des Texts in der Zeile, während die Ausrichtung des Texts bei justify am linken und
rechten Rand erfolgt. Es ist üblich und wird auch hier so gehandhabt, dass die letzte Zeile im Rechteck im justify-Modus linksbündig ausgerichtet wird, während im fulljustifyModus alle Zeilen (einschließlich der letzten, sofern sie mindestens ein Leer- oder Tabulatorzeichen enthält) am linken und rechten Rand ausgerichtet werden. fulljustify ist
dann sinnvoll, wenn der Text in einer anderen Spalte fortgesetzt werden soll.
feature Ist der Parameter feature auf blind gesetzt, dann erfolgen zwar alle nötigen Berechnungen (mit Ausnahme der internen Koordinaten textx und texty, die nicht aktualisiert werden), der Text wird aber nicht ausgegeben. Diese Möglichkeit kann genutzt werden, um Probeberechnungen durchzuführen und zum Beispiel herauszufinden, bei
welcher Schriftgröße ein Text genau in ein vorgegebenes Rechteck passt. Anderenfalls
muss feature leer sein.
Rückgabe Die Anzahl von Zeichen, die nicht verarbeitet werden konnten, weil der Text nicht vollständig in die Zeile passte. Passte der Text, wird 0 zurückgegeben. Da keinerlei Formatierung durchgeführt wird, wenn width = 0 und height = 0, gibt die Funktion in diesem
Fall immer 0 zurück.
Details Die aktuelle Schrift muss vor dem Aufruf dieser Funktion gesetzt worden sein. Für den
Text werden die aktuell eingestellten Werte für Schrift, Schriftgröße, horizontaler Abstand und Zeilenabstand verwendet. Die aktuelle Textposition wird ans Ende des generierten Texts verschoben.
4.3 Textfunktionen
95
Gültigkeit page, pattern, template; diese Funktion kann nicht bei CID-Schriften oder beim
Zeichensatz ebcdic verwendet werden.
Siehe auch Einschränkungen dieser Funktionen werden in Abschnitt 3.3.10, »Textmetrik, Textvarianten und
Formatierung in ein Rechteck«, Seite 67 beschrieben.
Function stringwidth(text As String, font As Long, size As Single) As Single
Gibt die Breite von text in einer beliebigen Schrift zurück.
text
Text, dessen Breite ermittelt wird.
font Fonthandle, das von PDF_findfont( ) zurückgegeben wurde. Die zugehörige Schrift
darf keine CID-Schrift sein. Bezieht sich font auf eine CID-Schrift, gibt diese Funktion
unabhängig von den Parametern text und size immer 0 zurück.
size
Textlänge, gemessen in Einheiten des benutzerdefinierten Koordinatensystems.
Details Diese Funktion gibt die Breite von text in beliebiger Schrift und der Größe size zurück.
Bei der Berechnung der Textbreite werden die aktuellen Werte folgender Textparameter
herangezogen: horizontale Skalierung, Zeichenabstand und Wortabstand. Der Parameter wordspacing wird ignoriert.
Gültigkeit page, pattern, template, path, document
4.4 Grafikfunktionen
4.4.1 Funktionen für den Grafikzustand
Alle Parameter, die sich auf den Grafikzustand beziehen, werden am Anfang jeder Seite
wieder auf ihre Standardwerte zurückgesetzt. Die Standardwerte werden bei den jeweiligen Funktionsbeschreibungen angegeben. Funktionen, die sich auf den Textzustand
beziehen, werden in Abschnitt 4.3, »Textfunktionen«, Seite 90, beschrieben.
Hinweis Keine der Funktionen für den Grafikzustand darf im Geltungsbereich path verwendet werden
(siehe Abschnitt 3.2, »Seitenbeschreibungen«, Seite 40).
Sub setdash(b As Single, w As Single)
Setzt das aktuelle Strichmuster.
b, w Anzahl der sich abwechselnden schwarzen bzw. weißen Einheiten. b und w müssen 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.
96
Sub setpolydash(darray)
Legt ein komplizierteres über ein Array definiertes Strichmuster fest.
darray Array mit Längenangaben für sich abwechselnde schwarze und weiße Striche.
Diese Arraywerte müssen positiv und dürfen nicht alle gleich null sein. Sie werden solange zyklisch verwendet, bis der Pfad komplett gezeichnet ist.
Details Um eine durchgezogene Linie zu erhalten, arbeiten Sie mit einem leeren Array. Die Arraylänge muss kleiner oder gleich 8 sein; anderenfalls wird das Array abgeschnitten. Am
Anfang jeder Seite wird das Strichmuster auf eine durchgezogene Linie gesetzt.
Sub setflat(flatness As Single)
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.
Sub setlinejoin(linejoin As Long)
Legt die Verbindungsart von Linien (linejoin-Parameter) fest.
linejoin
Legt die Form der Ecken in zu zeichnenden Pfaden fest (siehe Tabelle 4.8).
Details Am Anfang jeder Seite wird der linejoin-Parameter auf den Standardwert 0 gesetzt.
Tabelle 4.8 Werte für den linejoin-Parameter
Wert
Beschreibung (aus der PDF-Referenz)
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.
Beispiele
97
Sub setlinecap(linecap As Long)
Legt die Art der Linienenden (linecap-Parameter) fest.
linecap
Steuert die Art der Linienenden beim Zeichnen eines Pfads (siehe Tabelle 4.9).
Details Am Anfang jeder Seite wird der linecap-Parameter auf den Standardwert 0 gesetzt.
Tabelle 4.9 Werte für den linecap-Parameter
Wert
Beschreibung (aus der PDF-Referenz)
0
Abgeschnittene Linienenden: Die Linie wird am Endpunkt des Pfades
rechtwinklig abgeschnitten.
Beispiele
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.
Sub setmiterlimit(miter As Single)
Legt den Grenzwert für das Abschneiden spitzer Liniensegmente fest (miterlimit).
miter Ein Wert größer oder gleich 1, der festlegt, wie die
Spitze gezeichnet wird, die sich bei spitzen Verbindungen
(miter joins) ergibt.
Miter
length
Strichstärke
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 beiden Liniensegmente in einem schmalen Winkel zusammenlaufen. Diese Spitze wird abgeschnitten (das heißt die spitze Verbindung wird durch eine stumpfe ersetzt), wenn
das Verhältnis zwischen Spitzenbreite und Linienstärke den Wert des miterlimit-Parameters übersteigt. Am Anfang jeder Seite wird miterlimit auf den Standardwert 10 gesetzt. Dies entspricht einem Winkel von etwa 10,5 Grad.
Sub setlinewidth(width As Single)
Setzt die aktuelle Linienstärke.
width
Die Linienstärke in Einheiten des benutzerdefinierten Koordinatensystems
Details Am Anfang jeder Seite wird der Parameter width auf den Standardwert 1 gesetzt.
98
Sub initgraphics
Setzt alle Parameter, die sich auf Farbe und Grafikzustand beziehen, auf ihre Standardwerte zurück.
Details Die Parameter für Farbe (color), Linienstärke (linewidth), Linienende (linecap), Verbindungsart (linejoin), Grenzwert für spitze Verbindungen (miterlimit) und Strichmuster
(dash) sowie die aktuelle Transformationsmatrix (aber nicht die Parameter für den Textzustand) werden auf ihre jeweiligen Standardwerte zurückgesetzt. Der aktuelle Clipping-Pfad ist davon nicht betroffen.
Diese Funktion kann in Situationen nützlich sein, wo der Programmablauf die Verwendung von PDF_save( )/PDF_restore( ) oder die Vorbereitung des Grafikzustands für
ein nachfolgendes Template oder importiertes PDF nicht zulässt.
4.4.2 Speichern und Wiederherstellen des Grafikzustands
Sub save( )
Speichert den aktuellen Grafikzustand.
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öchte (zum Beispiel auf ein benutzerdefiniertes Koordinatensystem), ohne erneut explizit
alle relevanten Parameter einstellen zu müssen. Beim Speichern und Wiederherstellen
des Grafikzustandes werden folgende Parameter berücksichtigt:
> Grafikparameter: Clipping-Pfad, Koordinatensystem, aktuelle Position, Flatness,
Linienendenstil (linecap), Strichmuster (dash), Art der Verbindungslinien (linejoin),
Linienstärke (line width), Grenzwert für das Abschneiden spitzer Liniensegmente
(miter limit);
> Farbparameter: Linien- und Füllfarben;
> Textposition und andere auf Text bezogene Parameter (siehe Liste unten);
> einige PDFlib-Parameter (siehe Liste unten).
Paare aus save( ) und restore( ) können verschachtelt werden. Obwohl es für diese Art der
Verschachtelung keinen durch die PDF-Spezifikation bedingten Grenzwert gibt, dürfen
Anwendungen nicht mehr als neun Verschachtelungsebenen nutzen. Anderenfalls können Probleme beim Drucken auftreten, die sich aus Einschränkungen bei der von PDFViewern erzeugten PostScript-Ausgabe ergeben. Außerdem müssen einige Verschachtelungsebenen für den internen Gebrauch durch PDFlib reserviert bleiben.
Gültigkeit page, pattern, template; diese Funktion muss immer paarweise mit restore( ) auftreten.
Genauer gesagt müssen save( ) und restore( ) paarweise innerhalb der Seite, des Musters
odes des Templates auftreten.
Parameter Der save/restore-Mechanismus bezieht folgende Parameter ein: charspacing, wordspacing,
horizscaling, leading, font, fontsize, textrendering, textrise; nicht berücksichtigt werden die
Parameter fillrule, underline, overline und strikeout.
99
Sub restore( )
Stellt den zuletzt gespeicherten Grafikzustand wieder her.
Details Der entsprechende Grafikzustand muss innerhalb derselben Seite, desselben Musters
bzw. desselben Templates gespeichert worden sein.
Gültigkeit page, pattern, template; diese Funktion muss immer paarweise mit save( ) auftreten.
Genauer gesagt müssen save( ) und restore( ) paarweise innerhalb der Seite, des Musters
oder des Templates auftreten.
4.4.3 Funktionen zur Transformation des Koordinatensystems
Alle Transformationsfunktionen (translate( ), scale( ), rotate( ), skew( ), concat( ),
setmatrix( ) und initgraphics( )) ändern das Koordinatensystem, das beim Zeichnen nachfolgender Objekte verwendet wird. Sie haben keinerlei Einfluss auf bereits auf der Seite
vorhandene Objekte.
Sub translate(tx As Single, ty As Single)
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.
Sub scale(sx As Single, sy As Single)
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 Koordinatensystem entspricht sx Einheiten in x-Richtung im alten Koordinatensystem; entsprechendes gilt für die y-Koordinaten.
Visual-Basic-Benutzer müssen Abschnitt 2.2.9, »Einsatz von PDFlib mit Visual Basic«,
Seite 26, berücksichtigen und die Schreibweise oPDF.[scale] verwenden.
Sub rotate(phi As Single)
Dreht das benutzerdefinierte Koordinatensystem.
phi
Rotationswinkel in Grad.
Details Die Winkelmessung beginnt auf der positiven x-Achse des aktuellen Koordinatensystems und erfolgt gegen den Uhrzeigersinn. Die neuen Koordinatenachsen ergeben sich
aus einer Drehung der alten Koordinatenachsen um phi Grad.
100
Sub skew(alpha As Single, beta As Single)
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 übergebenen Winkel geneigt. alpha wird dabei von der positiven x-Achse des aktuellen Koordinatensystems 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.
Sub concat(a As Single, b As Single, c As Single, d As Single, e As Single, f As Single)
Konkateniert eine Matrix mit der aktuellen Transformationsmatrix.
a, b, c, d, e, f Elemente einer Transformationsmatrix. Die sechs Gleitkommazahlen
bilden eine Matrix 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
translate( ), scale( ), rotate( ) und skew( ) verwenden. Am Anfang jeder Seite wird die CTM
auf die Einheitsmatrix [1, 0, 0, 1, 0, 0] zurückgesetzt.
Sub setmatrix(a As Single, b As Single, c As Single, d As Single, e As Single, f As Single)
Setzt die aktuelle Transformationsmatrix explizit.
a, b, c, d, e, f
Siehe concat( ).
Details Diese Funktion entspricht im Wesentlichen concat( ) mit dem Unterschied, dass sie die
aktuelle Transformationsmatrix verwirft und vollständig durch eine neue Matrix ersetzt.
101
4.4.4 Pfadkonstruktion
Werte.
Tabelle 4.10 Parameter und Werte für Pfadsegmentfunktionen (siehe Abschnitt 4.2.3,
»Parameterbehandlung«, Seite 89)
Funktion
Schlüssel
Erklärung
get_value
currentx
currenty
Die x- bzw. y-Koordinate (in Einheiten des aktuellen Koordinatensystems)
der aktuellen Position. Geltungsbereich: page, pattern, template, path.
Hinweis Achten Sie darauf, immer eine der Funktionen aus Abschnitt 4.4.5, »Zeichnen und Beschneiden
von Pfaden«, Seite 104, aufzurufen, nachdem Sie die Funktionen in diesem Abschnitt verwendet haben. Sonst hat der konstruierte Pfad keinerlei Auswirkungen, und nachfolgende Operationen führen unter Umständen zu einer PDFlib-Exception.
Sub moveto(x As Single, y As Single)
Setzt die aktuelle Position.
x, y
Koordinaten der neuen aktuellen Position.
Details Am Anfang jeder Seite wird die aktuelle Position auf den Standardwert undefined gesetzt. Die aktuellen Grafikpositionen sowie die aktuelle Textposition werden getrennt
verwaltet.
Gültigkeit page, pattern, template, path; mit dieser Funktion beginnt der Geltungsbereich path.
Parameter currentx, currenty
Sub lineto(x As Single, y As Single)
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 Position 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
102
Sub curveto(x1 As Single, y1 As Single, x2 As Single, y2 As Single, x3 As Single, y3 As Single)
Zeichnet eine Bézier-Kurve, ausgehend von der aktuellen Position, wobei drei Kontrollpunkte berücksichtigt werden.
x1, y1, x2, y2, x3, y3
Koordinaten der drei Kontrollpunkte.
Details Der aktuelle Pfad wird um eine Bézier-Kurve zwischen der aktuellen Position und (x3,
y3) ergänzt, wobei (x1, y1) und (x2, y2) als Kontrollpunkte dienen. Die aktuelle Position
muss zuvor gesetzt worden sein. Der Endpunkt der Kurve wird zur neuen aktuellen Position.
Gültigkeit path
Sub circle(x As Single, y As Single, r As Single)
Zeichnet einen Kreis.
x, y
r
Koordinaten des Kreismittelpunkts.
Kreisradius.
Details Diese Funktion ergänzt den aktuellen Pfad um einen Kreis, der einen vollständigen Teilpfad darstellt. Der Punkt (x + r, y) wird zur neuen aktuellen Position. Die resultierende
Form ist, in benutzerdefinierten Koordinaten gemessen, kreisförmig. Wurde das Koordinatensystem in x- und y-Richtung unterschiedlich skaliert, ist die resultierende Kurve
eine Ellipse.
Visual-Basic-Benutzer müssen Abschnitt 2.2.9, »Einsatz von PDFlib mit Visual Basic«,
Seite 26, berücksichtigen und die Schreibweise oPDF.[circle] verwenden.
Sub arc(x As Single, y As Single, r As Single, alpha As Single, beta As Single)
Zeichnet ein Kreissegment gegen den Uhrzeigersinn.
x, y
r
Koordinaten des Mittelpunkts des Kreissegments
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 gezeichnetes Kreissegment, das bei alpha Grad beginnt und bei beta Grad endet. Sowohl bei arc( )
als auch bei arcn( ) werden die Winkel gegen den Uhrzeigersinn gemessen, und zwar ausgehend von der positiven x-Achse des aktuellen Koordinatensystem. 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 aktuellen Position.
103
Das Kreissegment ist, in benutzerdefinierten Koordinaten gemessen, kreisförmig.
Wurde das Koordinatensystem in x- und y-Richtung unterschiedlich skaliert, hat die resultierende Kurve eine elliptische Form.
Sub arcn(x As Single, y As Single, r As Single, alpha As Single, beta As Single)
Wie arc( ), nur dass das Kreissegment im Uhrzeigersinn gezeichnet wird.
Details Mit Ausnahme der Zeichenrichtung verhält sich diese Funktion genau wie arc( ). Beachten Sie, dass dies auch impliziert, dass die Winkel, ausgehend von der positiven x-Achse,
gegen den Uhrzeigersinn gemessen werden.
Sub rect(x As Single, y As Single, width As Single, height As Single)
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 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.
Sub closepath( )
Schließt den aktuellen Pfad.
Details Diese Funktion schließt den aktuellen Teilpfad, das heißt, sie zeichnet eine Linie zwischen der aktuellen Position und dem Startpunkt des Teilpfads.
Gültigkeit path
4.4.5 Zeichnen und Beschneiden von Pfaden
Werte.
Hinweis Die meisten in diesem Abschnitt beschriebenen Funktionen leeren den Pfad und lassen die aktuelle Position undefiniert. Auf diese Funktionen folgende Zeichenoperationen müssen die aktuelle Position explizit setzen (zum Beispiel mit moveto( )).
104
Tabelle 4.11 Parameter und Werte für die Funktionen zum Zeichnen und Beschneiden von Pfaden (siehe Abschnitt
4.2.3, »Parameterbehandlung«, Seite 89)
Funktion
Schlüssel
set_parameter fillrule
Erklärung
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.
Sub stroke( )
Zeichnet den Pfad und leert ihn.
Details Diese Funktion zeichnet den aktuellen Pfad mit der aktuellen Linienstärke und Linienfarbe.
Gültigkeit path; mit dieser Funktion endet der Geltungsbereich path.
Sub closepath_stroke( )
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.
Sub fill( )
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 Innere des Pfads wird durch einen von zwei Algorithmen bestimmt (siehe Parameter
fillrule). Offene Pfade werden vor dem Füllen geschlossen.
Parameter fillrule
Sub fill_stroke( )
Zeichnet und füllt den Pfad mit der aktuellen Zeichenfarbe und der aktuellen Füllfarbe.
Details Diese Funktion zeichnet und füllt den Pfad mit der aktuellen Zeichenfarbe und der aktuellen Füllfarbe.
Parameter fillrule
105
Sub closepath_fill_stroke( )
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 kompletten aktuellen Pfad.
Parameter fillrule
Sub clip( )
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, nämlich die Seitengröße gesetzt. Der Clipping-Pfad wird
vom save( )/restore( )-Mechanismus berücksichtigt. Er kann nur mittels save( )/restore( )
vergößert werden.
Sub endpath( )
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 unsichtbaren Pfad auf der Seite.
4.5 Farbfunktionen
Sub setcolor(type As String, colorspace as String, c1 As Single, c2 As Single, c3 As Single, c4
As Single)
Setzt den aktuellen Farbraum und die aktuelle Farbe.
type Einer der Werte stroke, fill oder both, die festlegen, ob die Farbe zum Zeichnen, Füllen oder für beides festgelegt wird.
colorspace
pattern.
Festlegung des Farbraums durch einen der Werte gray, rgb, cmyk, spot oder
c1, c2, c3, c4 Farbkomponenten für den ausgewählten Farbraum:
> 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;
106
> Ist colorspace gleich spot, enthält c1 das Handle für eine Schmuckfarbe, das von
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 begin_
pattern( ) erzeugt wurde.
Details Alle Farbwerte für die Farbräume gray, rgb und cmyk sowie für den Farbauftrag des Farbraums spot müssen Zahlen zwischen 0 (inklusive) und 1 (inklusive) sein. Nicht verwendete Parameter sollten auf 0 gesetzt werden.
Graustufenwerte, RGB-Werte und der Farbauftrag für Schmuckfarben werden gemäß additiver Farbmischung interpretiert, das heißt, 0 bedeutet »keine Farbe« und 1 bedeutet »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) ergeben weiß. CMYK-Werte dagegen werden gemäß subtraktiver Farbmischung interpretiert, 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 Bereich 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üllmusterfarbe gibt es keine Standardwerte.
Gültigkeit page, pattern (nur wenn der PaintType des Füllmusters gleich 1 ist), template, document;
eine Füllmusterfarbe kann nicht innerhalb ihrer eigenen Definition verwendet werden.
Die Farbe im Geltungsbereich document festzulegen, kann zur Definition von Schmuckfarben mit makespotcolor( ) sinnvoll sein.
Function makespotcolor(spotname As String) As Long
Erzeugt aus der aktuellen Füllfarbe eine Schmuckfarbe mit Namen.
spotname Beliebiger Name für die zu definierende Schmuckfarbe. Dieser kann beliebige Zeichen enthalten, ist aber auf eine Länge von maximal 126 Bytes beschränkt.
Rückgabe Ein Farbhandle, das in nachfolgenden Aufrufen von setcolor( ) im ganzen Dokument verwendet werden kann. Schmuckfarbenhandles können seitenübergreifend verwendet
werden, aber nicht in anderen Dokumenten. Die Anzahl der Schmuckfarben in einem
Dokument ist nicht begrenzt.
Details Die Farbwerte (CMYK oder andere) der aktuellen Füllfarbe werden nur zur Bildschirmanzeige oder für den Low-End-Druck verwendet. Für den High-End-Druck (oder Farbseparationen) wird statt der CMYK-Werte der übergebene Schmuckfarbenname verwendet. Beachten Sie, dass Sie zusätzliche Software benötigen, um Farbseparationen aus
PDF heraus zu erzeugen.
Wurde spotname bereits in einem früheren Aufruf von makespotcolor( ) verwendet,
ist der Rückgabewert wieder derselbe und gibt somit nicht die aktuelle Farbe wieder.
Der spezielle Schmuckfarbenname All kann verwendet werden, um eine Farbe in allen Farbseparationen zu verwenden. Dies kann zum Beispiel bei Schnittmarken sinnvoll sein. Der Schmuckfarbenname None produziert eine Ausgabe, die auf keinem Auszug sichtbar ist.
4.5 Farbfunktionen
107
Gültigkeit page, pattern, template, document; die aktuelle Füllfarbe darf keine Schmuckfarbe und
kein Füllmuster sein;
Function begin_pattern(width As Single, height As Single, xstep As Single, ystep As Single,
painttype As Long) As Long
Beginnt mit der Definition eines Füllmusters.
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 Farbspezifikation enthalten, die bei seinem Einsatz herangezogen wird; ist painttype gleich 2, darf das
Füllmuster keinerlei Farbspezifikation enthalten. Stattdessen wird die aktuelle Zeichenoder 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 setcolor( ) innerhalb
des umschließenden Geltungsbereichs document verwendet werden kann.
Details Hypertextfunktionen und Funktionen zum Öffnen von Rasterbildern dürfen innerhalb
einer Füllmusterdefinition nicht verwendet werden. Erlaubt sind dagegen alle Text-,
Grafik- und Farbfunktionen (mit Ausnahme des Füllmusters, das gerade definiert wird).
Gültigkeit document; mit dieser Funktion beginnt der Geltungsbereich pattern; diese Funktion
muss immer paarweise mit end_pattern( ) auftreten.
Sub end_pattern()
Beendet eine Füllmusterdefinition.
Gültigkeit pattern; mit dieser Funktion endet der Geltungsbereich pattern; diese Funktion muss
immer paarweise mit begin_pattern( ) auftreten.
Sub setgray_fill(g As Single)
Sub setgray_stroke(g As Single)
Sub setgray(g As Single)
Veraltet; verwenden Sie stattdessen setcolor(type, "gray", g, 0, 0, 0) mit type gleich fill,
stroke oder both.
Sub setrgbcolor_fill(red As Single, green As Single, blue As Single)
Sub setrgbcolor_stroke(red As Single, green As Single, blue As Single)
Sub setrgbcolor(red As Single, green As Single, blue As Single)
Veraltet; verwenden Sie stattdessen setcolor(type, "rgb", red, green, blue, 0) mit type gleich
fill, stroke oder both.
108
4.6 Rasterbildfunktionen
Die im Folgenden beschriebenen Funktionen zum Öffnen von Rasterbildern können innerhalb oder außerhalb von Seitenbeschreibungen aufgerufen werden. Wird ein Bild
außerhalb des durch begin_page( ) / end_page( ) gegebenen Kontexts geöffnet, so hat das
eine etwas geringere Ausgabegröße zur Folge.
Tabelle 4.12 enthält eine Übersicht aller für diesen Abschnitt relevanten Parameter
und Werte.
Tabelle 4.12 Parameter und Werte für die Rasterbildfunktionen (siehe Abschnitt 4.2.3,
Funktion
Schlüssel
get_value
imagewidth Ermittelt die Breite (width) bzw. Höhe (height) eines Bildes in Pixeln. Der
imageheight Modifizierer entspricht dem Handle des gewünschten Bilds. Geltungsbereich:
page, pattern, template, document, path.
Erklärung
get_value
resx
resy
Ermittelt die horizontale bzw. vertikale Auflösung eines Bilds. Der Modifizierer
entspricht dem Handle des gewünschten Bilds. Geltungsbereich: page, pattern,
template, document, path.
Ist der Rückgabewert positiv, 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 imagewarning
Dieser Parameter kann verwendet werden, um genauere Angaben darüber zu
erhalten, warum ein Bild mit open_image_file( ) oder open_CCITT( ) nicht
geöffnet werden konnte. Geltungsbereich: beliebig.
true
Beim Scheitern einer Bildfunktion wird eine nicht-fatale Exception
ausgelöst und -1 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 zurück.
Dieser Wert ist standardmäßig eingestellt.
Function open_image_file(type As String, filename As String, stringparam As String,
intparam As Long) As Long
Öffnet eine Bilddatei.
type Legt den Typ des Bildformats fest: png, gif, jpeg oder tiff (siehe Abschnitt 3.4.1,
»Unterstützte Rasterbildformate«, Seite 71). Bei allen Parametern wird zwischen Großund Kleinschreibung unterschieden.
filename
Name der zu öffnenden Bilddatei.
stringparam, intparam Die Parameter stringparam und intparam werden für weitere
Bildattribute verwendet, die in Tabelle 4.13 aufgeführt sind. Werden diese Parameter
nicht verwendet, dann muss stringparam ein Leerstring und intparam gleich 0 sein.
Rückgabe Handle für das Bild, das in nachfolgenden Aufrufen von Bildfunktionen verwendet werden kann. Der Rückgabewert muss auf den Wert -1überprüft werden, der einen Fehler
anzeigt. Um genauere Angaben über die Art eines bildspezifischen Problems zu erhalten
(zum Beispiel falscher Dateiname, nicht unterstütztes Format, fehlerhafte Bilddaten
109
etc.), setzen Sie den Parameter imagewarning auf true (siehe Tabelle 4.12). Das zurückgegebene Bildhandle 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 type festgelegt wurde. PDFlib öffnet die Bilddatei
mit dem ü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_place_image( )), die zugehörige Bilddatei ist
aber bereits wieder geschlossen.
Gültigkeit document, page; diese Funktion muss immer paarweise mit close_image( ) auftreten.
Parameter imagewidth, imageheight, resx, resy, imagewarning
Tabelle 4.13 Die Parameter stringparam und intparam von open_image_file( )
stringparam
Erklärung und mögliche Werte für intparam
mask
Erzeugt eine Maske aus einem Bild mit 1-Bit-Pixeltiefe. Weitere Informationen hierzu sowie eine
Liste der unterstützten Bildformate finden Sie in Abschnitt 3.4.5, »Bildmasken und Transparenz«,
Seite 76. Es gibt zwei Anwendungsfälle für Masken (der Parameter intparam wird in diesem Fall
ignoriert und muss gleich 0 sein):
Maskieren eines anderen Bilds: Das zurückgegebene Bildhandle wird später beim Öffnen eines
anderen Bilds verwendet und als Parameter »masked« übergeben.
Platzieren eines eingefärbten transparenten Bilds: Pixelwerte von 0 im Bild werden als
transparent interpretiert und die Werte von 1 werden mit der aktuellen Füllfarbe eingefärbt.
masked
Verwendet den in intparam übergebenen Bilddeskriptor als Maske für dieses Bild. Der Parameter
intparam enthält ein Bildhandle, das von einem vorangehenden Aufruf von open_image( ) mit
dem Parameter »mask« zurückgegeben und noch nicht geschlossen wurde.
ignoremask
Alle in der Bilddatei vorhandene Transparenzinformationen werden ignoriert.
invert
Bei 1-Bit-TIFF-Bildern wird schwarz und weiß invertiert. Dies dient in erster Linie als Behelfslösung
bei TIFF-Bildern, die von verschiedenen Anwendungen unterschiedlich interpretiert werden.
page
Das Bild mit der in intparam übergebenen Nummer wird aus einer mehrseitigen Datei extrahiert.
Das erste Bild hat die Nummer 1. Dieser Parameter wird nur bei mehrseitigen TIFF-Dateien
unterstützt.
colorize
Das Bild wird mit der in intparam übergebenen Schmuckfarbe, die mit makespotcolor( ) ermittelt
werden muss, eingefärbt. Das Bild muss ein Graustufenbild mit einer Farbtiefe von 1, 2, 4 oder 8
Bit in einem der Formate GIF, PNG, JPEG oder TIFF sein.
Function open_CCITT(filename As String, width As Long, height As Long, BitReverse As
Long, K As Long, BlackIs1 As Long) As Long
Öffnet ein CCITT-Rasterbild.
filename
Name der zu öffnenden CCITT-Datei.
width, height
BitReverse
tiert.
Die Abmessungen des Bilds in Pixeln.
Wenn gleich 1, wird in den komprimierten Daten jedes Byte bitweise inver-
K CCITT-Kompressionsparameter zur Auswahl des Kodierungsverfahrens.
> -1 bezeichnet G4-Kodierung.
> 0 bezeichnet eindimensionale G3-Kodierung (G3-1D).
110
> 1 bezeichnet eine Mischung aus ein- und zweidimensionaler Kodierung (G3, 2-D), die
von PDF unterstützt wird.
BlackIs1 Hat dieser Parameter den Wert 1, werden 1-Bits als schwarz und 0-Bits als weiß
interpretiert. Bei den meisten CCITT-Bildern wird keine Schwarz-Weiß-Invertierung verwendet, das heißt BlackIs1 = 0.
Rückgabe Bildhandle, das nachfolgend in Bildfunktionen verwendet werden kann, sofern es nicht
den Wert -1 hat. Da PDFlib keine CCITT-Bilder analysieren kann, müssen alle relevanten
Bildparameter vom Client an open_CCITT( ) übergeben werden.
Details Diese Funktion öffnet eine Bilddatei mit CCITT-G3- oder CCITT-G4-komprimierten Rasterbilddaten (jedoch nicht eine TIFF-Datei, die CCITT-komprimierte Bilddaten enthält!).
Function open_image(type As String, source As String, data, length As Long, width As Long,
height As Long, components As Long, bpc As Long, params As String) As Long
Arbeitet mit Rasterbilddaten aus verschiedensten Datenquellen.
type Legt die Art der Bilddaten oder Kompression fest: jpeg, ccitt oder raw (siehe Abschnitt 3.4.1, »Unterstützte Rasterbildformate«, Seite 71).
source, data, length Der Parameter source bestimmt, woher die Bilddaten kommen. Er
kann die Werte fileref, url und memory annehmen (siehe Abschnitt 3.4.4, »Bilddaten im
Speicher und externe Bildreferenzen«, Seite 76). Der Zusammenhang zwischen den Parametern source, data und length wird in Tabelle 4.14 erklärt.
width, height
Bildgröße in Pixeln.
components Die Anzahl der Farbkomponenten muss 1, 3, oder 4 sein, je nachdem, ob
Graustufen, RGB- oder CMYK-Bilddaten verwendet werden.
bpc Die Anzahl der Bits pro Komponente ist 1, 2, 4 oder 8. bpc muss auf 8 gesetzt werden, wenn type gleich jpeg ist, und auf 1, wenn type gleich ccitt ist.
params Ist components = 1 und bpc = 1, darf params auch mask enthalten, um das Bild als
Bildmaske zu verwenden. Außerdem können zusätzliche CCITT-Parameter übergeben
werden (siehe unten).
Rückgabe Bildhandle, das in nachfolgenden Bildfunktionen verwendet werden kann, sofern es
nicht gleich -1 ist.
Details Diese vielseitige Schnittstelle kann für Bilddaten in verschiedenen Formaten aus unterschiedlichen Datenquellen verwendet werden. Im Gegensatz zu open_image_file( ), das
eine Bilddatei analysiert, müssen die Parameter length, width, height, components, und
bpc hier vom Benutzer übergeben werden. open_image( ) analysiert die Bilddaten nicht,
und der Benutzer ist selbst dafür verantwortlich, dass die übergebenen Parameter die
tatsächlichen Bildeigenschaften widerspiegeln. Anderenfalls ist die generierte PDF-Ausgabe beschädigt, was von Acrobat dann unter Umständen mit der Meldung Nicht
genügend Daten für ein Bild beantwortet wird.
111
Tabelle 4.14 Werte für die Parameter source, data und length von open_image( )
source
data
length
fileref1
String2 mit einem plattformunabhängigen Dateinamen (siehe [1])
unbenutzt, sollte 0
sein
url1
String2 mit einem Bild-URL gemäß RFC 17383. Der URL wird noch nicht von unbenutzt, sollte 0
PDFlib, sondern erst beim Öffnen des PDF von Acrobat interpretiert (siehe sein
Abschnitt 3.4.4, »Bilddaten im Speicher und externe Bildreferenzen«, Seite
76). Dieses Feature ist rein experimenteller Natur und sollte deshalb im
produktiven Einsatz nicht verwendet werden.
memory
Länge der
Bytes mit den Binärdaten des Bildes; die Bilddaten sind gemäß des
Parameters type komprimiert. Es müssen genau »length« Bytes übergeben (komprimierten)
Bilddaten in Bytes
werden.
1. Wird im Kompatibilitätsmodus für Acrobat 3 nicht unterstützt.
2. data ist kein String sondern ein Byte-Array so dass die Übergabe von Dateinamen oder URLs etwas umständlich ist.
3. Der URL darf keine zusätzlichen Parameter, Query-Strings, Zugriffsschemata, Netzwerk-Logins oder Fragmentbezeichner enthalten.
Ist type gleich raw, muss length gleich [width x components x bpc / 8] x height Bytes
sein, wobei der Term in eckigen Klammern zur nächsten ganzen Zahl aufgerundet wird.
Es muss eine genau length entsprechende Datenmenge übergeben werden. Die Bildpunkte werden in der in PostScript/PDF üblichen Reihenfolge erwartet, das heißt, von
oben nach unten und von links nach rechts (sofern keine Koordinatentransformation
stattgefunden hat). Die Wertigkeit der Pixelwerte entspricht der Beschreibung in Abschnitt 3.2.3, »Pfade und Farben«, Seite 43. Auch wenn bpc ungleich 8 ist, beginnt eine Pixelzeile an einer Bytegrenze. Die Farbwerte innerhalb eines Bytes müssen von links
nach rechts eingetragen werden. Die Farbwerte eines Pixels sind immer gruppiert, das
heißt, alle Farbwerte für das erste Pixel werden zuerst übergeben, darauf folgen alle
Farbwerte für das zweite Pixel usw.
Ist type auf ccitt gesetzt, werden CCITT-komprimierte Daten erwartet. In diesem Fall
wird der Inhalt von params untersucht. Bei CCITT-Bildern können im params-String zwei
Parameter übergeben werden, so wie es bei open_CCITT( ) beschrieben wurde:
/K -1 /BlackIs1 true
Für /K werden die Werte -1, 0 und 1 unterstützt, der Standardwert ist 0. Für /BlackIs1 werden true und false unterstützt, der Standardwert ist false. Die Standardwerte werden verwendet, wenn ein leerer params-String übergeben wird. BitReverse kann in diesem String
nicht übergeben werden. Stattdessen gibt es eine besondere Konvention: ist length negativ, werden die Bilddaten bitweise invertiert.
Wird der Parameter params nicht verwendet, muss er leer sein. Der Client ist für den
Speicherplatz verantwortlich, auf den das data-Argument zeigt. Dieser Speicher kann
vom Client unmittelbar nach diesem Aufruf freigegeben werden.
Sie sollten keine mit Photoshop erzeugten CMYK-JPEG-Bilder mit dieser Funktion
verwenden, da diese im PDF mit invertierten Farben erscheinen.
112
Sub close_image(image As Long)
Schließt ein Bild.
Gültiges Bildhandle, das mit einer der Funktionen open_image*( ) erzeugt wur-
image
de.
Details Diese Funktion wirkt sich nur auf die im 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 open_image*( ) geschlossen wurde. Ein
mit dieser Funktion geschlossenes Bildhandle kann nicht weiter verwendet werden, da
damit die interne Verknüpfung des Bilds zu PDFlib gelöst wurde. Diese Funktion darf
nicht auf Bildhandles angewandt werden, die mit open_pdi_page( ) geöffnet wurden (in
diesem Fall müssen Sie mit close_pdi_page( ) arbeiten).
Gültigkeit document, page; diese Funktion darf nur paarweise mit einem entsprechenden Aufruf
von open_image_file( ), open_CCITT( ) oder open_image( ) auftreten.
Sub place_image(image As Long, x As Single, y As Single, scale As Single)
Platziert ein Bild oder Template mit der linken unteren Ecke an (x, y) und skaliert es.
Gültiges Bildhandle, das mit open_image*( ) oder begin_template( ) erzeugt wur-
image
de.
x, y Koordinaten im benutzerdefinierten Koordinatensystem, an denen sich die linke
untere Ecke des platzierten Bilds befinden soll.
scale
Skalierungsfaktor, der auf das Bild in x- und y-Richtung angewandt wird.
Details Weitere Informationen über Skalierung und dpi-Berechnung einschließlich ungleichmäßiger Skalierung (unterschiedliche Skalierungsfaktoren in x- und y- Richtung) finden
Sie in Abschnitt 3.4.2, »Häufig benötigte Codefragmente für Rasterbilder«, Seite 74.
Gültigkeit page, pattern, template; diese Funktion kann beliebig oft auf beliebigen Seiten
aufgerufen werden, solange das Bildhandle nicht mit close_image( ) geschlossen wird.
Parameter inheritgstate; Es wird dringend empfohlen, diesen Parameter auf false zu setzen;
Einzelheiten hierzu finden Sie in Abschnitt 3.2.4, »Templates«, Seite 44.
Tabelle 4.15 Parameter zur Platzierung von Templates und PDF-Seiten (siehe Abschnitt 4.2.3,
Funktion
Schlüssel
Erklärung
set_parameter inheritgstate Steuert die Übernahme (inheritance) der Grafikparameter von importierender
Seite bzw. des Template oder der importierten PDF-Seite. Geltungsbereich:
get_parameter
beliebig.
true
Grafikzustandsparameter können von der importierenden Seite ins
Template übernommen werden. Dies ist die Standardeinstellung.
false
Grafikzustandsparameter werden nie übernommen; die
importierende Seite und das Template sind voneinander unabhängig.
113
Function begin_template(width As Long, height As Long) As Long
Beginnt eine Template-Definition.
width, height
Die Größe der Boundingbox des Templates in Punkt.
Rückgabe Templatehandle, das in nachfolgenden Bildfunktionen, inbesondere place_image( ), verwendet werden kann. Es wird kein Fehler zurückgegeben.
Details Hypertextfunktionen 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; mit dieser Funktion beginnt der Geltungsbereich template; diese Funktion
muss immer paarweise mit end_template( ) auftreten.
Sub end_template( )
Beendet eine Template-Definition.
Gültigkeit template; mit dieser Funktion endet der Geltungsbereich template; diese Funktion muss
immer paarweise mit begin_template( ) auftreten.
4.7 Funktionen zum PDF-Import (PDI)
4.7.1 Dokument und Seite
Function open_pdi(filename As String, stringparam As String, intparam As Long) As Long
Öffnet ein in einer Datei vorliegendes PDF-Dokument und bereitet es zur späteren Verwendung vor.
filename
Name der PDF-Datei.
stringparam, intparam
Leerstring bzw. 0 sein.
Für zukünftige Versionen reserviert; muss momentan ein
Rückgabe Dokumentdeskriptor, der zur Verarbeitung einzelner Seiten des Dokuments oder zur
Abfrage von Dokumenteigenschaften verwendet werden kann. Ein Rückgabewert von -1
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 Um genauere Informationen über die Art des mit dem importierten PDF zusammenhängenden Problems zu erhalten (PDF-Dateiname falsch, Format nicht unterstützt,
PDF-Daten nicht korrekt etc.), setzen Sie den Parameter pdiwarning auf true.
Gültigkeit document, page
Parameter Siehe Tabelle 4.16 und Tabelle 4.17.
114
Sub close_pdi(doc As Long)
Schließt alle geöffneten PDI-Seitenhandle sowie das PDF-Importdokument.
doc
Gültiges PDF-Dokumenthandle, das mit open_pdi*( ) erzeugt wurde.
Details Diese Funktion schließt ein PDF-Importdokument und gibt alle Ressourcen frei, die sich
auf das Dokument beziehen. Alle unter Umständen offenen Dokumentseiten werden
geschlossen. Das Dokumenthandle darf nach Aufruf dieser Funktion nicht mehr benutzt werden. 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.
Function open_pdi_page(doc As Long, pagenumber As Long, pagelabel As String) As Long
Bereitet eine Seite zur späteren Verwendung mit place_pdi_page( ) vor.
doc
Gültiges Dokumenthandle, das mit open_pdi*( ) erzeugt wurde.
pagenumber
pagelabel
Nummer der zu öffnenden Seite. Die erste Seite hat die Seitennummer 1.
Reserviert; muss momentan ein Leerstring sein.
Rückgabe Seitendeskriptor, der zur Platzierung von Seiten mit place_image( ) verwendet werden
kann. Ein Rückgabewert von -1 zeigt an, dass die Seite nicht geöffnet werden konnte. Der
Rückgabewert kann bis zum Ende des umgebenden Geltungsbereichs document verwendet werden.
Details Um genauere 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.
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. Das mehrmalige Öffnen einer
Seite ist nicht empfehlenswert, da sämtliche Seitendaten dann auch mehrmals ins Ausgabedokument übernommen werden.
Siehe auch PDF_place_pdi_page( )
Sub close_pdi_page(page As Long)
Schließt das Seitenhandle und gibt alle Ressourcen frei, die sich auf die Seite beziehen.
page Gültiges PDF-Seitenhandle (keine Seitennummer!), das mit open_pdi_page( ) erzeugt wurde.
115
Details Diese Funktion schließt die Seite, die mit dem Seitenhandle page verknüpft ist, und gibt
alle zugehörigen Ressourcen frei. page darf nach diesem Aufruf nicht mehr verwendet
werden.
Sub place_pdi_page(page As Long, x As Single, y As Single, sx As Single, sy As Single)
Platziert eine PDF-Seite mit der linken unteren Ecke an der Position (x, y) und skaliert
sie.
page Gültiges PDF-Seitenhandle (keine Seitennummer!), das mit open_pdi_page( ) erzeugt wurde. Das Seitenhandle darf nicht bereits wieder geschlossen sein.
x, y Die Koordinaten im benutzerdefinierten Koordinatensystem, an denen die linke
untere Ecke der Seite platziert werden soll.
sx, sy Der horizontale und der vertikale Skalierungsfaktor, die auf die Seite angewandt
werden sollen.
Details Diese Funktion entspricht im Wesentlichen place_image( ), arbeitet aber mit importierten PDF-Seiten. Ein weiterer Unterschied besteht darin, dass an place_image( ) nur ein
einziger Skalierungsfaktor übergeben werden kann, während bei dieser Funktion eine
in x- und y-Richtung unabhängige Skalierung möglich ist.
Parameter Siehe Tabelle 4.15, Tabelle 4.16 und Tabelle 4.17.
4.7.2 Parameterbehandlung
Function get_pdi_value(key As String, doc As Long, page As Long, index As Long) As Single
Ermittelt einen numerischen PDI-Dokumentparameter.
key Name (Schlüssel) des zu ermittelnden Parameters, siehe Tabelle 4.16 und Tabelle
4.17.
doc
Gültiges PDF-Dokumenthandle, das von open_pdi( ) erzeugt wurde.
page Gültiges PDF-Seitenhandle (keine Seitennummer!), das von open_pdi_page( ) erzeugt wurde. Bei nicht seitenspezifischen Schlüsseln muss page gleich -1 sein.
index
Derzeit nicht benutzt, muss 0 sein.
Rückgabe Numerischer Wert, der aus dem Dokument ermittelt wird.
Gültigkeit beliebig
116
Tabelle 4.16 Seitenspezifische Werte beim PDF-Import
Funktion
Schlüssel
Erklärung
get_pdi_value
width
height
Ermittelt die Breite (width) oder Höhe (height) einer importierten
Seite in Standardeinheiten. Beschneidung und Drehung werden
berücksichtigt.
get_pdi_value
/Rotate
Seitendrehung in Grad (0, 90, 180 oder 270)
get_pdi_value
/CropBox,
/BleedBox,
/ArtBox,
/TrimBox
Fragt einen der Box-Parameter der Seite ab. Dem Parameternamen
muss ein Schrägstrich ’/’ und einer der Strings llx, lly, urx oder ury
folgen, zum Beispiel: /CropBox/llx. (Einzelheiten hierzu finden Sie
in Abschnitt 3.2.2, »Begrenzungen für Seiten und Koordinaten«,
Seite 42.) Beachten Sie, dass 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 worden wurde.
Function get_pdi_parameter(
key As String, doc As Long, page As Long, index As Long) As String
Ermittelt einen PDI-Dokumentparameter vom Typ String.
key Legt den Namen (Schlüssel) des zu ermittelnden Parameters fest, siehe Tabelle 4.16
und Tabelle 4.17.
doc
Gültiges PDF-Dokumenthandle, das von open_pdi( ) erzeugt wurde.
page Gültiges PDF-Seitenhandle (keine Seitennummer!), das von open_pdi_page( ) erzeugt wurde. Bei nicht seitenspezifischen Schlüsseln muss page gleich -1 sein.
index
Derzeit nicht benutzt, muss 0 sein.
Rückgabe String-Parameter, der aus dem Dokument ermittelt wurde. Unicode-Infostrings (/Info/
<key>) werden mit einleitendem BOM und abschließender Doppelnull zurückgegeben.
Derzeit erzeugt PDFlib kein Unicode-String-Objekt aus Dokumentinfo-Keys, die Unicode-Zeichen enthalten.
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 4.17 zeigt
sinnvolle Parameterkombinationen.
Gültigkeit beliebig
Tabelle 4.17 Dokumentspezifische Parameter und Werte zum PDF-Import. Der Parameter page muss -1 sein.
Funktion
Schlüssel
Erklärung
get_parameter
pdi
Gibt den String true zurück, wenn die PDI-Bibliothek installiert ist
(und nicht im Demo-Modus läuft), anderenfalls false.
Geltungsbereich: beliebig, null.
get_pdi_value
/Root/Pages/Count
Anzahl der Seiten im importierten Dokument
get_pdi_parameter
filename
Name der PDF-Datei
get_pdi_parameter
/Info/<Schlüssel>
Ermittelt den String-Wert eines Schlüssels im Info-Dictionary des
Dokuments, zum Beispiel /Info/Title. Der String wird nicht
konvertiert. Kann der Schlüssel im Dokument nicht gefunden
werden, wird ein Leerstring zurückgegeben. Ist pdiwarning auf
true gesetzt, wird dagegen eine Exception ausgelöst.
117
Tabelle 4.17 Dokumentspezifische Parameter und Werte zum PDF-Import. Der Parameter page muss -1 sein.
Funktion
Schlüssel
Erklärung
get_pdi_value
version
PDF-Versionsnummer, die mit 10 multipliziert wird, zum Beispiel 13
für PDF 1.3
set_parameter
pdiwarning
Anhand dieses Parameters erhalten Sie genauere Informationen
darüber, warum ein PDF-Dokument oder eine Seite nicht geöffnet
werden konnten:
true
Eine nicht-fatale Exception wird ausgelöst, wenn die
PDI-Funktion scheitert. Der mit der Exception gelieferte
Text kann bei der Behebung von import-spezifischen
Problemen behilflich sein.
false
Beim Scheitern einer PDI-Funktion wird keine Exception
ausgelöst. Stattdessen gibt die Funktion im Fehlerfall
-1 zurück. Dies ist die Standardeinstellung.
set_parameter
pdistrict
Mit diesem Parameter lässt sich das Verhalten von PDI bei
beschädigten Dateien steuern:
true
Bei nicht-konformen PDF-Dokumenten wird eine nichtfatale Exception ausgelöst, sofern der Parameter
warning nicht auf false gesetzt ist.
false
Bestimmte Arten von beschädigten PDF-Dokumenten
werden akzeptiert. Dies ist die Standardeinstellung.
set_parameter
pdiusebox
Dieser Parameter bestimmt, welcher der folgenden Box-Angaben
zur Ermittlung der Größe einer importierten Seite verwendet wird
(Standardeinstellung ist 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
Der Parameter pdiusebox muss vor dem Aufruf von open_pdi_
page( ) gesetzt werden.
4.8 Hypertextfunktionen
4.8.1 Aktion und Modus beim Öffnen des Dokuments
Tabelle 4.18 enthält eine Übersicht aller in diesem Abschnitt relevanten Parameter und
Werte. Diese Parameter können vor dem Aufruf von close( ) jederzeit gesetzt werden.
4.8.2 Lesezeichen
Tabelle 4.19 enthält eine Übersicht aller in diesem Abschnitt relevanten Parameter.
Hinweis Beim Hinzufügen von Lesezeichen wird der Öffnen-Modus (openmode) auf den Wert bookmarks gesetzt (siehe Abschnitt 4.8.1, »Aktion und Modus beim Öffnen des Dokuments«, Seite
118), sofern nicht explizit ein anderer Modus gesetzt wurde.
Function add_bookmark(text As String, parent As Long, open As Long) As Long
Fügt ein neues Lesezeichen ein, das unter parent oder auf oberster Ebene platziert wird.
text Enthält den Text des Lesezeichens. Dieser kann in PDFDocEncoding oder Unicode
kodiert sein. Die maximale Länge von text beträgt 255 Zeichen in PDFDocEncoding bzw.
118
Tabelle 4.18 Parameter für Aktion und Modus beim Öffnen des Dokuments (siehe Abschnitt 4.2.3,
Funktion
Schlüssel
Erklärung
set_parameter openaction
Legt die Aktion beim Öffnen des Dokuments fest, das heißt den Zoomfaktor für die
erste Dokumentseite. Mögliche Werte sind retain, fitpage, fitwidth, fitheight,
fitbbox (siehe Tabelle 4.25). Standardeinstellung ist retain. Geltungsbereich: page,
pattern, template, document.
set_parameter openmode
Legt das Aussehen beim Öffnen des Dokuments fest. Standardeinstellung ist
bookmarks, sofern das Dokument Lesezeichen enthält, andernfalls none.
Geltungsbereich: page, pattern, template, document.
none
Weder Lesezeichen noch Piktogramme werden eingeblendet.
bookmarks Öffnet das Dokument mit eingeblendeten Lesezeichen.
thumbnails Öffnet das Dokument mit eingeblendeten Piktogrammen.
fullscreen Öffnet das Dokument im Vollbildmodus (funktioniert im Browser
nicht).
Tabelle 4.19 Parameter für Lesezeichen (siehe Abschnitt 4.2.3, »Parameterbehandlung«, Seite 89)
Funktion
Schlüssel
set_parameter bookmarkdest
Erklärung
Legt fest, in welcher Vergrößerung die Zielseite des nachfolgend generierten
Lesezeichens angezeigt wird. Mögliche Werte sind retain, fitpage, fitwidth,
fitheight, fitbbox (siehe Tabelle 4.25). Dieser Parameter kann beliebig oft geändert
werden. Standardeinstellung ist retain.
126 Zeichen in Unicode. Aus praktischen Gründen sollte text jedoch nicht mehr als 32
Zeichen umfassen.
parent Wenn parent ein gültiges Lesezeichenhandle enthält, das von einem vorangehenden Aufruf von add_bookmark( ) zurückgegeben wurde, dann wird ein neues dem
übergebenen Handle untergeordnetes Lesezeichen angelegt. Auf diese Art lassen sich
beliebig verschachtelte Lesezeichenhierarchien erzeugen. Ist parent = 0, dann wird das
neue Lesezeichen auf oberster Ebene angelegt.
open Ist open gleich 0, dann sind untergeordnete Lesezeichen ausgeblendet. Ist open =
1, ist die gesamte Lesezeichenhierarchie sichtbar. Die Zielseite des Lesezeichens wird in
der aktuell eingestellten Vergrößerung angezeigt, die sich über den Parameter
bookmarkdest einstellen lässt (siehe Tabelle 4.19).
Rückgabe Handle für das gerade erzeugte Lesezeichen. Dieses Handle kann in nachfolgenden Aufrufen als Parameter parent verwendet werden.
Details Diese Funktion fügt ein PDF-Lesezeichen ein, das den übergebenen text enthält und auf
die aktuelle Seite zeigt. Der Zoomfaktor kann mit dem Parameter bookmarkdest gesteuert werden.
Gültigkeit page
Parameter openmode, bookmarkdest
119
4.8.3 Dokumentinfofelder
Sub set_info(key As String, value As String)
Trägt value in das Dokumentinfofeld key ein.
key Der Parameter key muss in PDFDocEncoding kodiert sein. key kann einen der Namen der fünf Standardinfofelder enthalten oder den Namen eines benutzerdefinierten
Feldes, der beliebig gewählt sein kann (siehe Tabelle 4.20). Die Anzahl der benutzerdefinierten Felder ist nicht beschränkt. Wenn Sie mit benutzerdefinierten Dokumentinfofeldern arbeiten, empfehlen wir einen Blick auf den Dublin Core Metadata Elementset.1
Tabelle 4.20 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
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
CreationDate, Producer und
ModDate
Benutzerdefiniertes Feld. PDFlib unterstützt beliebig viele Felder, deren Namen
aus allen druckbaren Zeichen außer den folgenden bestehen können: Leerzeichen
’ ’, %, (, ), <, >, [, ], {, }, / und #.
value String, der dem Parameter key zugewiesen wird. Er kann in PDFDocEncoding
oder Unicode kodiert sein. Durch Acrobat ist die Länge von value auf maximal 255 Bytes
beschränkt.
4.8.4 Seitenübergänge
In PDF-Dateien kann für besondere Effekte ein Seitenübergang festgelegt werden, der in
Präsentationen genutzt werden kann. In Acrobat lassen sich solche Effekte nicht generell für das gesamte Dokument oder einzelne Seiten festlegen, sondern Sie können nur
im Vollbildmodus genutzt werden. Mit PDFlib dagegen kann die Art und Dauer eines
Seitenübergangs für jede Seite einzeln gesetzt werden. Tabelle 4.21 enthält eine Übersicht über die in diesem Abschnitt relevanten Parameter und Werte.
1. Siehe http://purl.org/DC
120
Tabelle 4.21 Parameter und Werte für Seitenübergänge (siehe Abschnitt 4.2.3, »Parameterbehandlung«, Seite 89)
Funktion
Schlüssel
Erklärung
set_parameter transition
Bestimmt den Seitenübergang für die aktuelle und nachfolgende Seiten, der
solange gilt, bis ein anderer Übergangseffekt eingestellt wird. Es werden alle
unten angeführten Übergangstypen unterstützt. Ist type leer, dann wird der
Seitenübergang zurückgesetzt. Standardeinstellung ist replace. Geltungsbereich:
beliebig.
split
Die Seite wird wie ein Vorhang aufgezogen und gibt die nächste Seite
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. (Dies ist die
Standardeinstellung.)
set_value
Legt fest, wie lange (in Sekunden) die aktuelle Seite angezeigt wird.
Standardeinstellung ist eine Sekunde. Geltungsbereich: beliebig
duration
4.8.5 Dateianlagen
Sub attach_file(llx As Single, lly As Single, urx As Single, ury As Single, filename As String,
description As String, author As String, mimetype As String, icon As String)
Fügt einen Kommentar in Form einer Dateianlage hinzu.
llx, lly, urx, ury x- und y-Koordinaten der linken unteren und der rechten oberen Ecke
des Kommentarrechtecks im Standardkoordinatensystem.
filename
Name der Datei, die in das PDF-Dokument eingebettet werden soll.
description String mit einer Erklärung zur Dateianlage. Er kann in PDFDocEncoding
oder Unicode kodiert sein.
author String mit dem Namen oder der Funktion des Verfassers. Er kann in PDFDocEncoding oder Unicode kodiert sein.
mimetype MIME-Typ der Datei. Anhand dieses Typs entscheidet Acrobat, welches Programm bei Aktivierung der Dateianlage gestartet wird.
icon Definiert, auf welche Art die ungeöffnete Dateianlage in Acrobat angezeigt wird
(siehe Tabelle 4.22).
Tabelle 4.22 Symbolnamen für Dateianlagen
Symbolname
Symbolform
Symbolname
graph
pushpin
paperclip
tag
Symbolform
121
Details Diese Funktion fügt einen Kommentar in Form einer Dateianlage an dem festgelegten
Rechteck ein. PDF-Dateianlagen werden erst ab Acrobat 4 unterstützt und sind damit in
PDFlib im Kompatibilitätsmodus für Acrobat 3 nicht verfügbar. Außerdem können Dateianlagen im Acrobat Reader nicht verarbeitet werden, dort wird einfach ein Fragezeichen angezeigt. Dateianlagen können nur mit der Acrobat-Vollversion verwendet werden.
Die Farbe des Symbols, mit der die Dateianlage angezeigt wird, lässt sich mit set_
border_color() einstellen.
Gültigkeit page
4.8.6 Notizen
Hinweis Die Koordinatenübergabe für Kommentare unterscheidet sich von den Parametern der Funktion rect( ). Alle Kommentarfunktionen erwarten Parameter für die beiden Ecken, während bei
rect( ) die Koordinaten für eine Ecke sowie Breite und Höhe übergeben werden.
Sub add_note(llx As Single, lly As Single, urx As Single, ury As Single, contents As String,
title As String, icon As String, open As Long)
Fügt eine Notiz ein.
des Notizrechtecks in Standardkoordinaten (und nicht in möglicherweise transformierten Benutzerkoordinaten!). Acrobat positioniert die linke obere Ecke des Symbols an der
linken oberen Ecke des festgelegten Rechtecks.
contents Textinhalt der Notiz. Er kann in PDFDocEncoding oder Unicode kodiert sein.
Die maximale Länge von contents beträgt 65535 Bytes.
title Überschrift der Notiz. Sie kann in PDFDocEncoding oder Unicode kodiert sein. Die
maximale Länge von title beträgt 255 Zeichen für PDFDocEncoding und 126 Zeichen für
Unicode. Aus praktischen Gründen sollte title nicht länger als 32 Zeichen sein.
icon Definiert, auf welche Art die ungeöffnete Notiz in Acrobat angezeigt wird (siehe
Tabelle 4.23).
open
Die Notiz erscheint geöffnet, wenn open = 1, und geschlossen, wenn open = 0.
Details Diese Funktion fügt eine Notiz mit dem festgelegten Rechteck ein. Da erst Acrobat 4 unterschiedliche Symbole für Notizen bietet, werden sie im Kompatibilitätsmodus für
Acrobat 3 nicht unterstützt (der Parameter icon muss dann leer sein). Acrobat-3-Viewer
(und offensichtlich auch Unix-Versionen von Acrobat 4) zeigen unabhängig vom übergebenen Parameter icon immer das Textnotiz-Symbol (note) an.
Die Farbe des Symbols, mit der die Notiz angezeigt wird, lässt sich mit set_border_
color() einstellen.
Gültigkeit page
4.8.7 Verknüpfungen (Links)
Tabelle 4.24 enthält eine Übersicht aller für diesen Abschnitt relevanten Parameter.
Hinweis PDF unterstützt nur Verknüpfungen mit rechteckiger Form.
122
Tabelle 4.23 Symbolnamen für Notizen
Symbolname
Symbolform
Symbolname
comment
newparagraph
insert
key
note
help
Symbolform
paragraph
Tabelle 4.24 Parameter für Verknüpfungen (siehe Abschnitt 4.2.3, »Parameterbehandlung«, Seite 89)
Funktion
Schlüssel
set_parameter base
Erklärung
Definiert den Basis-URL des Dokuments. Dies ist sinnvoll, wenn ein Dokument, das
relative Webverknüpfungen auf andere Dokumente enthält, an einen anderen Ort
verschoben wird. Verweist der Basis-URL auf den »alten« Ort, ist sichergestellt,
dass relative Verknüpfungen auch weiterhin funktionieren. Geltungsbereich:
page, pattern, template, document.
Sub add_pdflink(llx As Single, lly As Single, urx As Single, ury As Single, filename As String,
page As Long, dest As String)
Fügt eine Verknüpfung auf eine bestimmte Seite einer PDF-Datei ein.
des Verknüpfungsrechtecks in Standardkoordinaten (und nicht in eventuell transformierten Benutzerkoordinaten!).
filename
page
Name der PDF-Zieldatei.
Physikalische Seitennummer der Zielseite.
dest Vergrößerung der Zielseite, wobei einer der in Tabelle 4.25 angeführten Werte
verwendet werden kann.
Gültigkeit page
Sub add_locallink(llx As Single, lly As Single, urx As Single, ury As Single, page As Long, dest
As String)
Fügt eine Verknüpfung auf eine Zielseite im aktuellen PDF-Dokument hinzu.
page Physikalische Seitennummer der Zielseite. Dies kann eine bereits generierte Seite oder eine Seite im selben Dokument sein, die erst später (nach der aktuellen Seite) ge-
123
neriert wird. Die Anwendung muss sicherstellen, dass die Zielseite auch tatsächlich generiert wird; anderenfalls gibt PDFlib eine Warnung aus.
dest Legt die Vergrößerung der Zielseite fest, wobei einer der in Tabelle 4.25 angeführten Werte verwendet werden kann.
Gültigkeit page
Tabelle 4.25 Werte für den Parameter dest in add_pdflink( ) und add_locallink( ). Dieselben Werte werden auch
beim Parameter openaction verwendet (siehe Abschnitt 4.8.1, »Aktion und Modus beim Öffnen des Dokuments«,
Seite 118) sowie beim Parameter bookmarkdest (siehe Abschnitt 4.8.2, »Lesezeichen«, Seite 118).
dest
Erklärung
retain
Übernimmt den bei Aktivierung der Verknüpfung aktuellen Zoomfaktor.
fitpage
Die ganze Seite wird im Fenster angezeigt.
fitwidth
Die Seitenbreite wird an die Fensterbreite angepasst.
fitheight
Die Seitenhöhe wird an die Fensterhöhe angepasst.
fitbbox
Passt die Boundingbox der Seite (das kleinste Rechteck, das alle Objekte umfasst) in das Fenster
ein.
Sub add_launchlink(llx As Single, lly As Single, urx As Single, ury As Single, filename As
String)
Fügt eine Verknüpfung auf eine Datei beliebigen Typs ein.
filename
tet wird.
Name der Datei, die beim Anklicken der Verknüpfung geöffnet oder gestar-
Gültigkeit page
Sub add_weblink(llx As Single, lly As Single, urx As Single, ury As Single, url As String)
Fügt eine Verknüpfung auf einen URL im Web ein.
url Ein Uniform Resource Identifier (Locator), der in 7-Bit ASCII kodiert ist und das Verknüpfungsziel festlegt. Er kann auf eine beliebige Ressource (im Web oder lokal) verweisen.
Gültigkeit page
Parameter Die Parameter textx/texty, currentx/currenty und imagewidth/imageheight können
verwendet werden, um Positionsdaten zur Größenberechnung von Verknüpfungsrechtecken zu ermitteln.
124
Sub set_border_style(style As String, width As Single)
Legt fest, wie der Rechteckrand dargestellt wird. Diese Einstellung bezieht sich auf alle
Arten von Verknüpfungen.
style Legt den Darstellungsstil des Rechteckrands fest. Er muss auf solid (durchgehend)
oder dashed (unterbrochen) gesetzt werden.
width Bestimmt die Breite des Rechteckrands in Punkten. Bei width = 0 ist der Rechteckrand unsichtbar.
Details Die mit dieser Funktion vorgenommenen Einstellungen werden solange auf alle Arten
von Verknüpfungen angewandt, bis ein neuer Stil festgelegt wird. Zu Beginn eines Dokuments wird die Darstellung des Rechteckrands auf die Standardeinstellung solid und 1
gesetzt.
Sub set_border_color(red As Single, green As Single, blue As Single)
Legt fest, in welcher Farbe der Rechteckrand dargestellt wird. Diese Einstellung bezieht
sich auf Verknüpfungen, Notizen und Dateinanlagen (annotations).
red, green, blue
RGB-Farbwerte für den Rechteckrand.
Details Die mit dieser Funktion vorgenommene Einstellung wird so lange auf alle Arten von
Verknüpfungen angewandt, bis eine neue Farbe festgelegt wird. Zu Beginn eines Dokuments wird die Farbe für den Rechteckrand auf schwarz (0, 0, 0) gesetzt.
Sub set_border_dash(b As Single, w As Single)
Legt fest, auf welche Art die Linie des Rechteckrandes unterbrochen dargestellt wird.
Diese Einstellung bezieht sich auf alle Arten von Verknüpfungen.
b, w
Legt die Art der unterbrochenen Randlinie fest (siehe setdash( )).
Details Zu Beginn eines Dokuments wird die Art der unterbrochenen Randlinie auf die
Standardeinstellung (3, 3) gesetzt. Diese Einstellung wird nur verwendet, wenn der Stil
des Rechteckrandes explizit auf dashed gesetzt wird.
4.8.8 Piktogramme (Thumbnails)
Sub add_thumbnail(image As Long)
Fügt ein vorhandenes Rasterbild als Piktogramm (Thumbnail) für die aktuelle Seite ein.
image Gültiges Bildhandle, das von einer der Funktionen open_image*( ) zurückgegeben wurde, aber kein Handle auf eine PDF-Seite oder ein Template.
125
Details Diese Funktion fügt das übergebene Bild als Piktogrammbild für die aktuelle Seite ein.
Damit 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 Piktogramm nur aus einem einzigen PDF-Bildobjekt bestehen darf. Multi-strip TIFF-Bilder werden jedoch in mehrere PDF-Bildobjekte konvertiert (siehe Abschnitt 3.4.1,
»Unterstützte Rasterbildformate«, Seite 71).
Diese Funktion erzeugt keine Piktogramme für die Seiten, sondern bietet lediglich die
Möglichkeit, bereits vorhandene Bilder hinzuzufügen, die gegebenenfalls als Piktogramme verwendet werden. Die tatsächlichen Miniaturseiten müssen vom Client oder
einer anderen Anwendung erstellt werden. Der Client muss dabei sicherstellen, dass die
Farben, das Seitenverhältnis sowie der tatsächliche Inhalt eines Piktogramms zum entsprechenden Seiteninhalt passen.
Da Acrobat 5 Piktogramme dynamisch generiert (wenngleich nicht im Browser) und
die generierte PDF-Datei durch Piktogramme 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 entsprechende Piktogramme.
Parameter openmode
4.9 Seitenformate
Zum schnellen Nachschlagen enthält Tabelle 4.26 übliche Seitenformate1.
Tabelle 4.26 Ü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
1008
A1
1684
2380
A5
421
595
legal
612
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:
http://www.twics.com/~eds/paper/papersize.html, http://www.cl.cam.ac.uk/~mgk25/iso-paper.html
126
5 Die PDFlib-Lizenz
PDFlib ist unter zwei Lizenzmodellen verfügbar, die sich grundsätzlich voneinander unterscheiden und damit die Interessen verschiedener Entwicklergruppen berücksichtigen. Lesen Sie die kurzen Zusammenfassungen bitte aufmerksam durch, damit Sie entscheiden können, welche Variante sich für Ihre Zwecke am besten eignet.
5.1 Die »Aladdin Free Public License«
(Dieser Abschnitt ist in der vorliegenden Ausgabe nicht enthalten, da er hier nicht von
Bedeutung ist.)
5.2 Die kommerzielle PDFlib-Lizenz
Es gibt verschiedene Lizenzierungsmöglichkeiten für den Einsatz von PDFlib auf einem
oder mehreren Servern und für die Weitergabe von PDFlib in eigenen Produkten. Außerdem bieten wir Wartungs- und Supportverträge. Einzelheiten zur Lizenzierung sowie das PDFlib-Bestellformular finden Sie in der PDFlib-Distribution. Bitte wenden Sie
sich an uns, wenn Sie Fragen haben oder eine kommerzielle PDFlib-Lizenz beziehen
möchten:
PDFlib GmbH
Tal 40, 80331 München
http://www.pdflib.com
Tel. +49 • 89 • 29 16 46 87
Fax +49 • 89 • 29 16 46 86
Vertriebsinformationen: [email protected]
Support für PDFlib-Lizenznehmer: [email protected] (Lizenznummer angeben)
Für anderweitige Auskünfte können Sie unsere Mailing-Liste durchsehen:
http://groups.yahoo.com/group/pdflib.
5.1 Die »Aladdin Free Public License«
127
6 Literaturhinweise
[1] Adobe Systems Incorporated: PDF Reference, Third Edition: Version 1.4; Verlag Addison-Wesley 2001, ISBN 0-201-75839-3; auch als PDF-Dokument erhältlich unter
http://partners.adobe.com/asn/developer/technotes.html
[2] Adobe Systems Incorporated: PostScript Language Reference Manual, Third Edition.
Verlag Addison-Wesley 1999, ISBN 0-201-37922-8; auch als PDF-Dokument erhältlich unter: http://partners.adobe.com/asn/developer/technotes.html
[3] Das folgende Buch vom Hauptentwickler von PDFlib behandelt zahlreiche Themen
zu PostScript, PDF und Schriften. Sie erhalten es versandkostenfrei direkt bei PDFlib
GmbH und in jeder Buchhandlung:
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
http://www.pdflib.com, [email protected]
128
Kapitel 6: Literaturhinweise (ActiveX/COM- und .NET-Edition)
(Dieser Abschnitt ist in der vorliegenden Ausgabe des PDFlib-Handbuchs nicht enthalten.)
129
Allgemeine Funktionen
Funktionsprototyp
Seite
Function open_file(filename As String) As Long
87
Function get_buffer( )
88
Sub close( )
88
Sub begin_page(width As Single, height As Single)
88
Sub end_page( )
89
Function get_value(key As String, modifier As Single) As Single
89
Sub set_value(key As String, value As Single)
89
Function get_parameter(key As String, modifier As Single) As String
90
Sub set_parameter(key As String, value As String)
90
Textfunktionen
Funktionsprototyp
Function findfont(fontname As String, encoding As String, options As Long) As Long
Seite
91
Sub setfont(font As Long, fontsize As Single)
92
Sub show(text As String)
94
Sub show_xy(text As String, x As Single, y As Single)
94
Sub continue_text(text As String)
94
Function show_boxed(text As String, x As Single, y As Single, width As Single, height As Single, mode As
String, feature As String) As Long
95
Function stringwidth(text As String, font As Long, size As Single) As Single
96
Sub set_text_pos(x As Single, y As Single)
92
Grafikfunktionen
Funktionsprototyp
130
Seite
Sub setdash(b As Single, w As Single)
96
Sub setpolydash(darray)
97
Sub setflat(flatness As Single)
97
Sub setlinejoin(linejoin As Long)
97
Sub setlinecap(linecap As Long)
98
Sub setmiterlimit(miter As Single)
98
Sub setlinewidth(width As Single)
98
Sub save( )
99
Sub restore( )
100
Sub translate(tx As Single, ty As Single)
100
Sub scale(sx As Single, sy As Single)
100
Sub rotate(phi As Single)
100
Sub skew(alpha As Single, beta As Single)
101
Sub concat(a As Single, b As Single, c As Single, d As Single, e As Single, f As Single)
101
Kapitel B: PDFlib-Kurzreferenz (ActiveX/COM- und .NET-Edition)
Funktionsprototyp
Seite
Sub moveto(x As Single, y As Single)
102
Sub lineto(x As Single, y As Single)
102
Sub curveto(x1 As Single, y1 As Single, x2 As Single, y2 As Single, x3 As Single, y3 As Single)
103
Sub circle(x As Single, y As Single, r As Single)
103
Sub arc(x As Single, y As Single, r As Single, alpha As Single, beta As Single)
103
Sub arcn(x As Single, y As Single, r As Single, alpha As Single, beta As Single)
104
Sub rect(x As Single, y As Single, width As Single, height As Single)
104
Sub closepath( )
104
Sub stroke( )
105
Sub closepath_stroke( )
105
Sub fill( )
105
Sub fill_stroke( )
105
Sub closepath_fill_stroke( )
106
Sub clip( )
106
Sub endpath( )
106
Farbfunktionen
Funktionsprototyp
Seite
Sub setcolor(type As String, colorspace as String, c1 As Single, c2 As Single, c3 As Single, c4 As Single) 106
Function makespotcolor(spotname As String) As Long
107
Function begin_pattern(width As Single, height As Single, xstep As Single, ystep As Single, painttype As
Long) As Long
108
Sub end_pattern()
108
Rasterbildfunktionen
Funktionsprototyp
Seite
Function open_image_file(type As String, filename As String, stringparam As String, intparam As Long)
As Long
109
Function open_CCITT(filename As String, width As Long, height As Long, BitReverse As Long, K As Long,
BlackIs1 As Long) As Long
110
Function open_image(type As String, source As String, data, length As Long, width As Long, height As
Long, components As Long, bpc As Long, params As String) As Long
111
Sub close_image(image As Long)
113
Sub place_image(image As Long, x As Single, y As Single, scale As Single)
113
Function begin_template(width As Long, height As Long) As Long
114
Sub end_template( )
114
131
Funktionen für den PDF-Import (PDI)
Funktionsprototyp
Seite
Function open_pdi(filename As String, stringparam As String, intparam As Long) As Long
114
Sub close_pdi(doc As Long)
115
Function open_pdi_page(doc As Long, pagenumber As Long, pagelabel As String) As Long
115
Sub close_pdi_page(page As Long)
115
Sub place_pdi_page(page As Long, x As Single, y As Single, sx As Single, sy As Single)
116
Function get_pdi_value(key As String, doc As Long, page As Long, index As Long) As Single
116
Function get_pdi_parameter( key As String, doc As Long, page As Long, index As Long) As String
117
Hypertextfunktionen
Funktionsprototyp
Seite
Function add_bookmark(text As String, parent As Long, open As Long) As Long
118
Sub set_info(key As String, value As String)
120
Sub attach_file(llx As Single, lly As Single, urx As Single, ury As Single, filename As String, description As
String, author As String, mimetype As String, icon As String)
121
Sub add_note(llx As Single, lly As Single, urx As Single, ury As Single, contents As String, title As String,
icon As String, open As Long)
122
Sub add_pdflink(llx As Single, lly As Single, urx As Single, ury As Single, filename As String, page As Long,
dest As String)
123
Sub add_locallink(llx As Single, lly As Single, urx As Single, ury As Single, page As Long, dest As String) 123
Sub add_launchlink(llx As Single, lly As Single, urx As Single, ury As Single, filename As String)
124
Sub add_weblink(llx As Single, lly As Single, urx As Single, ury As Single, url As String)
124
Sub set_border_style(style As String, width As Single)
125
Sub set_border_color(red As Single, green As Single, blue As Single)
125
Sub set_border_dash(b As Single, w As Single)
125
Sub add_thumbnail(image As Long)
125
Parameter und Werte
Kategorie
Funktion
Schlüssel
Konfiguration set_parameter prefix, resourcefile, compatibility, serial, warning
set_value
compress
get_value
major, minor, revision
get_parameter version, scope
Dokument
Schrift
Text
set_value
pagewidth, pageheight
CropBox, BleedBox, ArtBox, TrimBox: danach muss ein Schrägstrich ’/’
sowie llx, lly, urx oder ury folgen, zum Beispiel CropBox/llx
get_value
pagewidth, pageheight
set_parameter FontAFM, FontPFM, FontOutline, Encoding, fontwarning
set_value
leading, textrise, horizscaling, textrendering, charspacing, wordspacing
get_value
leading, textrise, horizscaling, textrendering, charspacing, wordspacing,
textx, texty, font, fontsize, capheight, ascender, descender
set_parameter underline, overline, strikeout, nativeunicode
get_parameter underline, overline, strikeout, fontname, fontencoding
132
Kapitel B: PDFlib-Kurzreferenz (ActiveX/COM- und .NET-Edition)
Kategorie
Grafik
Rasterbild
Funktion
Schlüssel
set_parameter fillrule
get_value
currentx, currenty
get_value
imagewidth, imageheight, resx, resy
set_parameter imagewarning
PDI
get_parameter pdi, inheritgstate
set_parameter pdiwarning, pdistrict, inheritgstate, pdiusebox
Hypertext
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_
parameter
filename, /Info/<key>
set_parameter openaction, openmode, bookmarkdest, transition, base
set_value
duration
133
C Änderungen an diesem Handbuch
Informationen über die PDFlib-Versionen finden Sie in der Quellcodedistribution.
Revisionsübersicht dieses Handbuchs
Datum
Änderungen
6. August 2002
> Deutsche Übersetzung des Handbuchs für PDFlib 4.0.3, Ergänzungen für .NET
> Kleinere Änderungen für PDFlib 4.0.3 und Erweiterungen für die .NET-Bindung
> Kleinere Änderungen für PDFlib 4.0.2 und Erweiterungen für die IBM-eServer-
14. Juni 2002
26. Januar 2002
Edition
17. Mai 2001
1. April 2001
5. Februar 2001
22. Dezember 2000
> Kleinere Änderungen für PDFlib 4.0.1
> Dokumentiert PDI- und andere Funktionen von PDFlib 4.0.0
> Dokumentiert Template- und CMYK-Funktionen in PDFlib 3.5.0
> ColdFusion-Dokumentation und Erweiterungen für PDFlib 3.03; separate
ActiveX-Edition des Handbuchs
8. August 2000
1. Juli 2000
20. Februar 2000
2. August 1999
29. Juni 1999
1. Februar 1999
10. August 1998
8. Juli 1998
25. Februar 1998
22. September 1997
134
> Delphi-Dokumentation und kleinere Erweiterungen für PDFlib 3.02
> Erweiterungen und Klarstellungen für PDFlib 3.01
> Änderungen für PDFlib 3.0
> Kleinere Änderungen und Erweiterungen für PDFlib 2.01
> Eigene Abschnitte für die jeweiligen Sprachbindungen
> Erweiterungen für PDFlib 2.0
> Kleinere Änderungen für PDFlib 1.0 (keine öffentliche Freigabe)
> Erweiterungen für PDFlib 0.7 (nur für einen Kunden)
> Erste Beschreibung der PDFlib-Skriptunterstützung in PDFlib 0.6
> Kleine Erweiterungen am Handbuch für PDFlib 0.5
> Erste öffentliche Version von PDFlib 0.4 und dieses Handbuchs
Kapitel C: Änderungen an diesem Handbuch (ActiveX/COM- und .NET-Edition)
Index
0-9
16-Bit-Zeichensatz 65
8-Bit-Zeichensätze 46, 65
A
Acrobat 3/4/5, Kompatibilität 13
Active Server Pages 22
besondere Hinweise 22
und PDFlib.NET 37
ActiveX-Sprachbindung
allgemein 16
Fehlerbehandlung 20
im eigenen Produkt 20
Registrierung der DLL 20
Unicode-Unterstützung 21
Versionskontrolle 21
add_bookmark() 118
add_launchlink() 124
add_locallink() 123
add_note() 122
add_pdflink() 123
add_thumbnail() 125
add_weblink() 124
Adobe Font Metrics (AFM) 54
Adobe Glyph List (AGL) 49, 65
AFM (Adobe Font Metrics) 54
AGL (Adobe Glyph List) 49, 65
aktueller Punkt 44
Aladdin Free Public License 127
All (Schmuckfarbname) 107
Alphakanal 77
Anlagen 65, 121
API (Application Programming Interface)
PDFlib-API-Referenz 85
äquidistante Schrift 68
arc() 103
arcn() 104
ArtBox 42, 87, 117, 118, 132, 133
AS/400 46
ascender-Parameter 68, 91
asiatisches Fontpaket 60
attach_file() 121
Ausgabegenauigkeit 43
Author-Feld 120
Automation 17
B
Baseline-Kompression 72
base-Parameter 123
begin_page() 88
begin_pattern() 108
begin_template() 114
benutzerdefinierter Zeichensatz 48
Beschneiden 43
Betriebssystemschriften 55
Bézier-Kurve 103
Bildfunktionen 109
Bildmasken 76, 79
BitReverse 110
BlackIs1 111
BleedBox 42, 87, 117, 118, 132, 133
blind Modus 70, 95
bookmarkdest-Parameter 119
bookmarks 119
Borland Delphi: siehe Delphi
builtin-Zeichensatz 46, 47
C
C++-Sprachbindung 32
capheight-Parameter 68, 91
CCITT 73, 110
Character ID (CID) 60
characters per inch (CPI) 68
charspacing-Parameter 93
chinesisch 60, 62
CID-Schriften 60
circle() 103
Probleme bei VB 26
CJK (chinesisch, japanisch, koreanisch) 60
clip() 106
Clipping 43
close() 88
close_image() 113
close_pdi() 115
close_pdi_page() 115
closepath() 104
closepath_fill_stroke() 106
closepath_stroke() 105
CMaps 60, 62
Codepage
8-Bit 48
IBM 1047 47
Microsoft Windows 1250-1258 50
Microsoft Windows 1252 47
Unicode-basiert 65
ColdFusion
Fehlerbehandlung 30
Index
135
colorize 110
COM (Component Object Model): siehe ActiveXSprachbindung
compatibility-Parameter 86
compress-Parameter 87
concat() 101
continue_text() 94
CPI (characters per inch) 68
Creator-Feld 120
CropBox 42, 87, 117, 118, 132, 133
C-Sprachbindung 32
currentx- und currenty-Parameter 67, 102
curveto() 103
D
Dateianlagen 65, 121
Delphi 30
Fehlerbehandlung 31
Demostempel 7
descender-Parameter 68, 91
Deskriptor 53
DLL (dynamic link library) 19, 129
Dokumentfunktionen 87
Dokumentinfofelder 65, 120
Dokumentöffnen-Aktion 118
Downsampling 74
dpi-Berechnungen 74
Drehen von Objekten 40
Dublin Core 120
duration-Parameter 121
dynamische Bibliotheken 129
E
EBCDIC 16, 47
ebcdic-Zeichensatz 46, 47
Einbetten von Fonts 53
Einfärben von Bildern 110
Einheiten 40
Embedded-Systeme 14
Encoding: siehe Zeichensatz
Encoding-Parameter 90
end_page() 89
end_pattern() 108
end_template() 114
endpath() 106
Errors-Klasse 20
Eurozeichen 47, 51
Exception: siehe Fehlerbehandlung
explizite Transparenz 78
externe Referenz auf Bilddaten 76
F
Farbe 44
Farbfunktionen 106
136
Index
Fehlerbehandlung 15, 39
in .NET 33
in ActiveX 20
in ColdFusion 30
in Delphi 31
in JScript 24
in VBScript 25
in Visual Basic 27
fetter CJK-Text 63
filename-Parameter 117
fill() 105
fill_stroke() 105
Filling 43
fillrule-Parameter 105
findfont() 91
FontAFM-Parameter 90
fontencoding-Parameter 90
Fontmetrik 67
fontname-Parameter 90
FontOutline-Parameter 90
font-Parameter 90
FontPFM-Parameter 90
Fonts
AFM-Dateien 54
allgemein 46
äquidistante 68
asiatisches Fontpaket 60
CID-Schriften 60
Deskriptor 53
einbetten 53
Glyphennamen 51
OpenType 53, 55
PDF-Standardschriften 46
PFA-Dateien 54
PFB-Dateien 54
PFM-Dateien 54
PostScript 54
rechtliche Aspekte der Einbettung 56
Ressourcekonfiguration 57
TrueType 55
Type 1 54
Type 3 54
UnicodeUnterstützung 65
fontsize-Parameter 90
FontSpecific-Encoding 47
fontwarning-Parameter 91
form XObjects 44
Füllen 43
Funktionalität von PDFlib 12
G
Geltungsbereich von Funktionen 85
get_buffer() 38, 88
get_parameter() 90
get_pdi_parameter() 116, 117
get_value() 89
GIF 72, 109
global.asa 22
Grafikfunktionen 96
Grafikzustand, Funktionen 96
grid.pdf 40
GUID 21
H
Hello world Beispiel
allgemein 14
für ASP/JScript 23
für ASP/VBScript 23
für C# 34
für ColdFusion 29
für Delphi 30
für VB.NET 35
für VBScript 28
für Visual Basic 27
Hochstellen von Text 68
horizontaler Text 60, 63
horizscaling-Parameter 93
host-Zeichensatz 46, 47
Hypertext
Funktionen 118
Zeichensatz 52
I
ignoremask 79, 110
imagewarning-Parameter 71, 109
imagewidth- und imageheight-Parameter 109
implizite Transparenz 78
Importfunktionen für PDF 114
in-core PDF-Erzeugung 38
Info-Schlüssel in importierten PDF-Dokumenten
117
inheritgstate-Parameter 113
initgraphics() 99
Installation, Silent für ActiveX 18
InstallShield 20
Internet Service Provider 19
invert 110
ISO 10646 65
ISO 8859-1 47, 52
ISO 8859-2 bis -15 50
J
japanisch 60, 62
Java-Sprachbindung 32
JFIF 72
JPEG 12, 72, 109, 112
JScript 23
Fehlerbehandlung 24
K
Kachelung 44
Kategorien von Ressourcen 58
Keywords-Feld 120
Kommentare 65, 122
Kompatibilität
Acrobat 3-5 12
Acrobat Reader 12
Koordinatenbereich 43
Koordinatensystem 40
metrisch 40
Top-Down 41
koreanisch 60, 62
K-Parameter für CCITT-Bilder 110
L
Latin-1-Zeichensatz 47, 52
Laufweite 68
leading-Parameter 68, 93
Lesezeichen 65, 118
ausblenden 119
lineto() 102
Links 122
Literaturhinweise 128
Lizenzierung
Modelle 127
PDFlib und PDI 7
LWFN (LaserWriter Font) 54
LZW-Kompression 72, 83
M
Mac OS Classic
UPR-Konfiguration 58
macroman-Zeichensatz 46, 47
major-Parameter 87
makepsres Hilfsprogramm 57
makespotcolor() 107
mask 78, 110
masked 78, 110
Maskierung von Bildern 76
MediaBox 42
mehrseitige Bilddateien 80
Metadaten 120
Metrik 67
metrische Koordinaten 40
Microsoft Transaction Server 17
Millimeter 40
minor-Parameter 87
monospaced: siehe äquidistant
moveto() 102
MSI 18
MTS 17
N
nativeunicode-Parameter 66, 67, 93
.NET
und ASP 37
.NET-Sprachbindung 32
Fehlerbehandlung 33
Index
137
Versionskontrolle 33
nicht-proportionale Bildskalierung 75
None (Schmuckfarbname) 107
Notizen 65, 122
O
Oberlänge 68
open_CCITT() 110
open_file() 87
open_image() 111
open_image_file() 109
open_pdi() 114
open_pdi_page() 115
openaction-Parameter 119
openmode-Parameter 119
OpenType-Schriften 53, 55
overline-Parameter 69, 93
P
page 80, 110
pagewidth- und pageheight-Parameter 87
Parameter
ascender 91
base 123
bookmarkdest 119
capheight 91
charspacing 93
compatibility 86
compress 87
currentx und currenty 67, 102
descender 91
duration 121
Encoding 90
filename 117
fillrule 105
font 90
FontAFM 90
fontencoding 90
fontname 90
FontOutline 90
FontPFM 90
fontsize 90
fontwarning 91
horizscaling 93
imagewarning 71, 109
imagewidth und imageheight 109
inheritgstate 113
leading 93
major 87
minor 87
nativeunicode 66, 67, 93
openaction 119
openmode 119
overline 69, 93
pageheight und pagewidth 87
pdi 117
pdistrict 118
138
Index
pdiusebox 82, 118
pdiwarning 118
prefix 86
resourcefile 86
resx und resy 109
revision 87
scope 87
serial 86
strikeout 69, 93
textrendering 63, 69, 93
textrise 93
textx und texty 67, 71, 93
transition 121
underline 69, 93
version 87, 118
warning 39, 86
width und height 117
wordspacing 93
Parameterbehandlungsfunktionen 89
Pattern-Farbraum 44
PDFDocEncoding 52
PDF-Importbibliothek PDI 80
PDF-Importfunktionen 114
PDFlib
Funktionalität 12
Programmstruktur 38
Thread-Sicherheit 11, 16
PDI 80
pdi-Parameter 117
pdistrict-Parameter 118
pdiusebox-Parameter 82, 118
pdiwarning-Parameter 118
Perl-Sprachbindung 37
PFA (Printer Font ASCII) 54
Pfad 43
zeichnen und beschneiden 104
PFB (Printer Font Binary) 54
PFM (Printer Font Metrics) 54
Photoshop 112
PHP-Sprachbindung 37
Piktogramme 119, 125
place_image() 113
place_pdi_page() 116
Plattformen 14
PNG 71, 78, 109
Portable Document Format Reference Manual
128
PostScript Language Reference Manual 128
PostScript-Schriften 54
prefix-Parameter 86
print_glyphs.ps 51
Printer Font ASCII (PFA) 54
Printer Font Binary (PFB) 54
Printer Font Metrics (PFM) 54
ProgID 21
Programmstruktur 38
Python-Sprachbindung 37
Q
Querformat 89
R
Rasterbilder
allgemein 71
Bildmasken 79
Daten im Speicher 76
Daten wiederverwenden 76
Downsampling 74
externe Referenz 76
Formate 71
Funktionen 109
nicht-proportional skalieren 75
Rohdaten 73
skalieren 74
Transparenz 76
Raw-Bilddaten 111
rect() 104
Reflexion 100
Registrierung der PDFlib-ActiveX-DLL 20
regsvr32 19
resourcefile-Parameter 86
Ressourcekategorie 58
restore() 100
resx- und resy-Parameter 109
revision-Parameter 87
RGB-Farbe 44
Rohbilddaten 73
rotate() 100
Rotate-Eintrag in importierten PDF-Seiten 117
RPG-Sprachbindung 37
S
S/390 46
save() 99
scale() 100
Probleme bei VB 26
Schmuckfarbe (Separation-Farbraum) 44
Schriften: siehe Fonts
scope-Parameter 87
Seitenbeschreibungen 40
Seitenformate 126
Begrenzungen in Acrobat 42
Seitenfunktionen 87
Seitenübergänge 120
Separation-Farbraum 44
serial-Parameter 7, 86
set_border_color() 125
set_border_dash() 125
set_border_style() 125
set_info() 120
set_parameter() 60
set_text_pos() 92
set_value() 89
setcolor() 106
setdash() 96
setflat() 97
setfont() 92
setgray() 108
setgray_fill() 108
setgray_stroke() 108
setlinecap() 98
setlinejoin() 97
setlinewidth() 98
setmatrix() 101
setmiterlimit() 98
setpolydash() 97
setrgbcolor() 108
setrgbcolor_fill() 108
setrgbcolor_stroke() 108
Setup-Funktionen 86
shared objects 129
show() 94
show_boxed() 70, 95
show_xy() 94
Silent-Install 18
Skalieren von Rasterbildern 74
skew() 101
Speicher
Bilddaten im 76
Erzeugung von PDF-Dokumenten im 38
Spiegelung 100
SPIFF 72
Sprachbindungen 14
Standardkoordinatensystem 40
Standardschriften 46
Standardseitemaße 126
Standardzoom 119
strikeout-Parameter 69, 93
stringwidth() 69, 96
stroke() 105
Stroking 43
Struktur von PDFlib-Programmen 38
Subject-Feld 120
subscript 68, 93
superscript 68, 93
Symbole
für Dateianlagen 121
für Notizen 123
Symbolschrift 47
T
T1lib 54
Tcl-Sprachbindung 37
Teilpfad 43
Templates 44
Text
Darstellungsmodi 69
Formatierung in Rechteck 67
Funktionen 90
hochstellen 68
Laufweite 68
Oberlänge 68
Index
139
Position 67
tiefstellen 68
Umrisslinien zeichnen 69
unsichtbarer 69
Unterlänge 68
Versalhöhe 68
vertikal und horizontal 60, 63
Zeilenabstand 68
text position 92
Textbehandlung 46
Textmetrik 67
textrendering-Parameter 63, 69, 93
textrise-Parameter 93
Textvarianten 67
textx- und texty-Parameter 63, 67, 71, 93
Threading-Modell 17
Thread-Sicherheit 11, 16
Thumbnails: siehe Piktogramme
Tiefstellen von Text 68
TIFF 73, 109
mehrseitig 80
Title-Feld 120
Top-Down-Koordinaten 41
transition-Parameter 121
translate() 100
Transparenz 76
explizite 78
implizite 78
Probleme mit 79
Trapped-Feld 120
TrimBox 42, 87, 117, 118, 132, 133
TrueType-Schriften 55
TTF (TrueType Font) 55
Type-1-Schriften 54
Type-3-Schriften 54
U
UCS-2 67
Umrisslinien von Text zeichnen 69
UNC 22
underline-Parameter 69, 93
Unicode 16, 65
in .NET 33
in ActiveX 21
in ColdFusion 30
in Delphi 31
in JScript 25
in VBscript 25
in Visual Basic 27
Probleme bei Sprachbindungen 66
unsichtbarer Text 69
Unterlänge 68
UPR (Unix PostScript Resource) 57
Dateiformat 57
Dateisuche 59
URL 76, 124
140
Index
user space 40
V
VBA 18
vbObjectError 21
VBScript 23, 28
Fehlerbehandlung 25
Verfügbarkeit von PDFlib 14
Verknüpfungen 122
Versalhöhe 68
version-Parameter 87, 118
Versionskontrolle
allgemein 15
in .NET 33
in ActiveX 21
vertikaler Text 60, 63
virtuelles Verzeichnis 22
Visual Basic 26
Fehlerbehandlung 27
Visual Basic .NET 35
Visual Basic for Applications 18
Visual Basic Scripting Edition: siehe VBScript
W
warning-Parameter 39, 86
Warnung 42
Webverknüpfung 124
Weitergabe der ActiveX-Komponente 20
Wert: siehe Parameter
width- und height-Parameter 117
winansi-Zeichensatz 46, 47
Windows Installer 18
Windows Script Host (WSH) 28
wordspacing-Parameter 93
X
XObjects 44
Z
ZapfDingbats-Schrift 47
Zeichennamen 51
Zeichensätze 46
benutzerdefiniert 48
CJK 64
für Hypertext 52
Unicode 65
Zeichnen 43
Zeilenabstand 68
Zoll 40
Zoomfaktor 119

Version 4.0.3

Transcription

Similar documents

PDFlib-Tutorial 9.0.3

Mediale Formen zwischen Intermedialität und

Das Planungskonzept eines Zen

PDFlib TET Referenzmanual

Der Wirtschaftsmodellversuch MEDIA

Weiteren - Sudetendeutsche Landsmannschaft