1. Dokumentation zu fly2pdf
0.) Vorwort
Dies ist der erste Versuch einer Dokumentation für die Bibliothek fly2pdf. Grundsätzlich wurde
versucht so dicht wie möglich an den PDF-Spezifikationen zu programmieren. Ein Studium der
aktuellen Version wird deshalb empfohlen.
Zur Demonstration wird die Sprache VBScript des „Windows Scripting Host“ verwendet. Das
ermöglicht das Testen der Bibliothek auf allen Windows-Systemen auf denen dieser installiert ist.
Er ist kostenlos bei Microsoft erhältlich und auf den meisten Rechnern vorinstalliert.
1.) Die Bibliothek
Die Bibliothek besteht aus vielen Objekten. Das wichtigste Objekt ist das Dokument-Objekt. Dieses
Objekt muss man sich als einen Container vorstellen, der unterschiedliche andere Objekte wie z.B.
Seiten, Schriftarten, Inhaltsverzeichnisse, eingebettet Dateien, Anmerkungen, Aktionen, Hyperlinks
usw. enthalten kann und diese miteinander verknüpft..
Erzeugt wird ein Dokument wie folgt:
' Erstellen eines Dokument Objektes
Set doc = WScript.CreateObject("fly2pdf.clsDocument", "fly2pdf_")
Der zweite Parameter fly2pdf_ definiert den Prefix für die Ereignisse.
Für viele Variablen sind Konstanten erforderlich. Alle verfügbaren Konstanten sind in der Datei
Constants.vbs definiert.
Zunächst schauen wir uns das minimalste Skript an um eine PDF-Datei mit einer Seite ohne Text
mit Hilfe fly2pdf zu erzeugen.
' Erstellen eines Dokument Objektes (auf Ereignisse wird
' verzichtet).
Set doc = WScript.CreateObject("fly2pdf.clsDocument")
' Erstellen eines Seiten Objektes – Es werden die Standard-
' einstellungen verwendet – also A4.
Set page = Wscript.CreateObject("fly2pdf.clsPage")
' Die Seite wird dem Dokument hinzugefügt.
doc.AddObject (page)
' Die PDF-Datei wird erzeugt.
doc.CreateFile("OnePage.pdf")
Um einen Text auf eine Seite zu plazieren, müssen wir folgendes tun. Wir fügen eine Seite, eine
Schriftart und einen Text dem Dokument hinzu und verknüpfen dann den Text mit der Seite (oder
anders gesagt, wir plazieren den Text auf die Seite).
2. ' Erstellen eines Schriftart(Font)-Objektes
Set font = WScript.CreateObject("fly2pdf.clsFont")
' Festlegen der Schriftart-Types.
font.FontSubType = eFontSubType_Type1
' Als Schriftart wird Helvetica gewählt.
font.Name = eFontType1_Helvetica
' Die Schriftart wird dem Dokument hinzugefügt.
doc.AddObject (font)
' Erstellen eines Seiten-Objektes
Set page = WScript.CreateObject("fly2pdf.clsPage")
' Die Seite wird dem Dokument hinzugefügt.
pID = doc.AddObject((page))
Im Augenblick werden nur die 14 Basisschriftarten (Type1-Schriftart) unterstützt. TrueType-
Schriftarten sind nicht möglich. Aus diesem Grund kann nur die Konstante eFontSubType_Type1
für die Variable gewählt font.FontSubType werden. In der Variablen pID wird die interne ID
eines Seiten-Objektes gespeichert. Diese ID wird später benötigt um ein Inhaltsobjekt auf eine
Seitenobjekt zu plazieren. Auch die ID des hinzugefügten Seiten-Objektes wird in einer ID
gespeichert. Um einen Text auf eine Seite zu plazieren, muss ein Inhalts-Objekt (content object)
dem Dokument hinzugefügt werden. Ein Inhalts-Objekt selbst kann verschieden Funktions-,
Zeichen- und Text-Objekte enthalten. Eines davon ist das Text-Objekt. Es gibt jedoch noch viele
andere Inhalts-Objekte. Wurde eine Schriftart dem Dokument noch nicht hinzugefügt, so passiert
dies spätestens beim Hinzufügen des ersten text-Objektes innerhalb eines Inhaltsobjektes.
' Erstellen eines Inhalts(content)-Objektes
Set cont = WScript.CreateObject("fly2pdf.clsContent")
' Ein TextBox-Object wird innerhalb eines Inhalts-Objektes
' erstellt.
cont.Text "Hello world.", (font), 12, 50, 100
' Das Inhalts-Objektes wird dem Dokument hinzugefügt.
contID = doc.AddObject((cont))
' Das Inhalts-Objektes wird mit Seite verknüpft.
doc.AddObjectToPage CLng(pID), CLng(contID)
Alle Parameter des Text-Objektes können in der fly2pdf.xml Datei nachgelesen werden. Zum
Schluss wird das Inhalts-Objekt zum Seiten-Objekt hinzugefügt.
Jetzt kann das PDF-Dokument erstellt. Dafür verwenden wir die Funktion Create des Dokument-
Objektes.
' Erzeugen der PDF-Datei
doc.Create("HelloWorld.pdf")
Das ganze nun als komplettes VBSkript. Im Gegensatz zu den Beispielen werden in diesem Skript
alle Konstanten mit implementiert. Die Beispiel-Skripte sind als Windows Scripting Host Dateien
3. erstellt wurden, weil sich so Include-Dateien verwenden lassen und sich die Übersichtlichkeit
wesentlich erhöht.
' HelloWorld script
' Part of fly2pdf
' Version: 1.0.0.0
' Author: Frank Heindörfer
' Comments: This script creates a pdf file with the sentence
' 'Hello world.' using the activex dll fly2pdf.
Option Explicit
Const eFontSubType_Type1 = 1, eFontType1_Helvetica = 4
Dim fso, Scriptname, ScriptBasename
Dim doc, font, page, cont, pID, contID
Set fso = CreateObject("Scripting.FileSystemObject")
Scriptname = fso.GetFileName(Wscript.ScriptFullname)
ScriptBasename = fso.GetFileName(Wscript.ScriptFullname)
Set doc = Wscript.CreateObject("fly2pdf.clsDocument", "fly2pdf_")
Set page = Wscript.CreateObject("fly2pdf.clsPage")
pID = doc.AddObject((page))
Set font = Wscript.CreateObject("fly2pdf.clsFont")
font.FontSubType = eFontSubType_Type1
font.Name = eFontType1_Helvetica
Set cont = Wscript.CreateObject("fly2pdf.clsContent")
cont.Text "Hello world.", (font), 12, 50, 100
contID = doc.AddObject((cont))
doc.AddObjectToPage CLng(pID), CLng(contID)
doc.CreateFile(fso.GetBaseName(ScriptBasename) & ".pdf")
4. Das Dokument-Objekt
Beschäftigen wir uns etwas näher mit dem Dokument-Objekt, da es das zentrale Objekt von fly2pdf
ist. Um Eigenschaften und Methoden des Dokument-Objektes zu erforschen, verwenden die zur wir
entweder einen Objekt-Browser (Gibt es standardmäßig bei Visual Basic oder MS Office mit
dazu.)
5. Eigenschaften
Eigenschaft Typ Beschreibung
CancelCreation Boolean Bricht die Erstellung des Dokumentes ab.
DocumentID1, String Legt die beiden Dokumenten-IDs einer PDF-Datei fest. Diese werden standardmäßig erzeugt, wenn die Eigenschaft UseDocumentID =
DocumentID2 TRUE gesetzt wird. Die DocmentID wird dazu verwendet um eine PDF-Datei eindeutig zu machen, obwohl ihr Inhalt möglicherweise
gleich aussieht.
Encryption clsEncryption Fügt dem Dokument-Objekt ein Verschlüsselungs-Objekt hinzu, damit eine verschlüsselte PDF-Datei erstellt werden kann.
OpenAction clsOpenAction Legt eine Aktion fest, die beim Öffnen einer PDF-Datei vom Anzeigeprogramm ausgeführt werden soll. (Falls das entsprechende
Anzeigeprogramm dies unterstützt.)
PageMode Long Legt eine Ansicht fest, die beim Öffnen einer PDF-Datei vom Anzeigeprogramm ausgeführt werden soll. (Falls das entsprechende
Anzeigeprogramm dies unterstützt.)
Der Standardwert ist -1, dass bedeutet das PageMode bei der Erstellung der PDF-Datei keine Berücksichtigung findet.
Möglich Konstanten sind:
ePageMode_UseNone = 0 ' Keine spezielle Ansicht ist definiert.
ePageMode_UseOutlines = 1 ' Zeige ein vorhandenes Inhaltsverzeichnis an.
ePageMode_UseThumbs = 2 ' Zeige eine kleine Bildervoschau aller Seiten.
ePageMode_FullScreen = 3 ' Öffnet das Dokument in der Vollbildanzeige.
Separator String Legt das bzw. die Trennzeichen fest. Standardmäßig ist dies ein „Carriage Return“ - CR. Es kann jedoch auch ein „Carriage Return
Line Feed“ - CRLF festgelegt werden, um eine PDF-Datei besser in einem Texteditor anzeigen lassen zu können.
StreamEncoding Collection Legt die Standardkodierung für interne PDF-Streams fest.
Möglich Konstanten sind:
eEncoding_NoEncoding = 0 ' Keine kodierung verwenden.
eEncoding_ASCIIHexEncode = 1 ' ASCII-Hex-Kodierung wird verwendet.
eEncoding_ASCII85Encode = 2 ' ASCII85-Kodierung wird verwendet.
eEncoding_RunLengthEncode = 3 ' RLE-Kodierung wird verwendet.
eEncoding_FlateEncode = 4 ' Zip-Kodierung wird verwendet. Dafür muss die freie
' zlib-Bibliothek (zlib.dll) im Pfad vorhanden sein.
UseDocumentID Boolean Wird dieser Wert auf TRUE gesetzt, wird eine DokumentID verwendet.
ViewerPreferences clsViewerPreferences Hier können Eigenschaften des Anzeigeprogrammes festgelegt werden. (Falls das entsprechende Anzeigeprogramm dies unterstützt.)
Public HideToolbar As Boolean ' True: Versteckt die Werkzeugleiste des Anzeigeprogrammes.
Public HideMenubar As Boolean ' True: Versteckt das Menü des Anzeigeprogrammes.
Public HideWindowUI As Boolean ' True: Versteckt alle grafischen Elemente des
6. Eigenschaft Typ Beschreibung
' Anzeigeprogrammes.
Public FitWindow As Boolean ' True: Passt die erste Seite des Dokumentes an das Fenster
' des Anzeigeprogrammes an.
Public CenterWindow As Boolean ' True: Zentriert das Fenster des Anzeigeprogrammes auf
' dem Bildschirm.
Public NonFullScreenPageMode As Long ' True: Öffnet das Dokument nicht in der
' Vollbildanzeige.
Public Direction As Long ' Legt die Leserichtung des Dokumentes fest.
' 0: Von Links nach Rechts.
' 1: Von Rechts nach Links.
Version String Legt die Version einer PDF-Datei fest. Standardmäßig verwendet fly2pdf die Version 1.3. Dies hat jedoch mehr symbolisch Charakter,
da fly2pdf nicht alle Spezifikationen der Version 1.3 unterstützt. Andererseits werden bereits Merkmale neuer Versionen enthalten
sind.
7. Prozeduren, Funktionen
Name Deklaration/Beschreibung
AddObject Public Function AddObject(Obj As Object) As Long
Fügt dem Dokument-Objekt ein Objekt zu. Zurückgegeben wird die interne ID des hinzugefügten Objektes. Diese wird für Verknüpfungen benötigt.
Möglich Objekte sind:
clsAnnotation ' Anmerkungs-Objekt
clsContent ' Inhalts-Objekt (kann selbst wiederum viele Objekte enthalten)
clsFont ' Schriftart-Objekt
clsPage ' Seiten-Objekt
AddObjectToPage Public Sub AddObjectToPage(PageID As Long, ObjID As Long)
Verknüpft ein Objekt mit einer Seite.
CreateFile Public Function CreateFile(Filename As String, Optional DontCreate As Boolean, Optional Linearization As
Boolean) As Long
Erstellt die PDF-Datei.
Filename ' der Dateiname
DontCreate ' Die Erstellung der Datei wird abgearbeitet. Es wird jedoch keine Datei gespeichert.
' Nützlich um die Größe der Datei zu erfahren ohne sie zu erstellen.
Linearization ' Soll das PDF-Objekt linearisiert gespeichert werden. Diese Option wird noch NICHT
' unterstützt.
CreateByteArray Public Function CreateByteArray(ByRef PDFByteArray() As Byte, Optional Linearization As Boolean) As Long
Erzeugt ein Byte-Feld, dass die Daten der PDF-Datei enthält. Es wird keine Datei erstellt.
PDFByteArray()' Feld, dass die daten enthält
Linearization ' Soll das PDF-Objekt linearisiert gespeichert werden. Diese Option wird noch NICHT
' unterstützt.
8. Ereignisse
Eigenschaft Deklaration/Beschreibung
Error Public Event Error(ID As Long, Description As String)
Löst ein Fehlereignis aus. ID enthält die Fehlerkennung, Description die Beschreibung. Mögliche Fehler sind:
-1 Die zu erzeugende Datei ist in Verwendung.
Progress Public Event Progress(ID As Long, ProgressMessage As String, ProgressValue As Long, ProgressMax
As Long)
Löst ein Fortschrittsereignis aus. ID enthält die Fortschrittskennung, ProgressMessage die Fortschrittsbeschreibung, ProgressValue den
aktuellen Fortschrittswert und ProgressMax den maximalen Fortschrittswert. Mit Hilfe von ProgressValue und ProgressMax können so
prozentuale Angaben über den Fortschritt während der Erstellung eines Dokumentes gemacht werden.
9. Zeichnen von Linien, Kurven, Rechtecke und Kreise
Zeichenelemente wie Linien, Kurven, Rechtecke und Kreise werden mit Hilfe des Inhalts-Objektes
gezeichnet.
Einige wichtige Funktionen des Inhaltsobjektes sind:
Zeichnen einer Linie.
Public Sub LineFromTo(X1 As Double, Y1 As Double, X2 As Double, Y2 As Double)
Zeichnen einer Bezier-Kurve.
Public Sub Bezier(X1 As Double, Y1 As Double, X2 As Double, Y2 As Double, X3 As
Double, Y3 As Double)
Zeichnen eines Rechteckes.
Public Sub Rectangle(x As Double, Y As Double, Width As Double, Height As
Double)
Zeichnen einer Ellipse.
Public Sub Ellipse(x As Double, Y As Double, rh As Double, rv As Double)
Zeichnen ausführen (ohne diesen Befehl wird kein Element auf eine Seite gezeichnet). Mit dem
Zeichenstil wird der die Art der Linie festgelegt.
Public Sub Draw(DrawStyle As Long)
Zeichenfarbe festlegen.
Public Sub StrokeColor(Color As OLE_COLOR)
Füllfarbe festlegen.
Public Sub FillColor(Color As OLE_COLOR)
Viele weitere Funktionen stehen zur Verfügung und können im Objektkatalog nachgeschlagen
werden.
Das nächste Beispiel demonstriert einige Funktionen.
11. Bilder
Bilder (hier geht ausschlißlich um Bitmap-Bilder) werden ebenfalls über das Inhalts-Objektes
gezeichnet. Dabei ist zu beachten das JPEG-Bilder direkt importiert werden können. Normalerweise
werden Bilder in ihre RGB-Anteile zerlegt und entsprechend des vorgegeben Kodierungsverfahrens
gespeichert. Da das PDF-Format den direkten Import von JPEG-Bildern erlaubt, ist es möglich
diese auch direkt in eine PDF zu importieren (dies hat nichts mit der Einbettung von Dateien über
Anmerkungen zu tun). Es ist aber auch möglich JPEG-Bilder neu zu kodieren und das wiederum
mit der Kodierungsart „DCTEncoding“ was einer erneuten JPEG-Komprimierung entspricht. Dies
kann zu einer weiteren Verringerung der Dateigröße führen.
Zeichnen eines Bildes.
Public Sub Image(FilenameOrHDC As Variant, x As Double, y As Double, Width As
Double, Height As Double, Optional Encoding As Variant, Optional JPEGDirect As
Boolean = True)
Parameter Beschreibung
FilenameOrHDC Ein Dateiname oder ein HDC (Handle eines Device Context)
x, y Linke untere Adresse des Bildes
Width, Height Höhe und Breite des Bildes
Encoding Kodierungsart:
Möglich Kodierungen sind:
NoEncoding = keine Kodierung
ASCIIHexEncode = ASCII-Hex-Kodierung
ASCII85Encode = ASCII85-Kodierung
RunLengthEncode = RLE-Kodierung
FlateEncode = ZIP-Kodierung
DCTEncode = DCT-Kodierung
Encoding ist vom Typ Variant und kann statt eines einzelnen Parameters
(vom Typ Long) auch genauso eine Collection. Dadurch sind mehrstufige
Kodierungen möglich (also erst DCTEncode dann ASCII85Encode). Für
Umgebungen die den Datentyp Collection nicht unterstützen, wurde die
Klasse clsCollection implementiert.
JPEGDirect Soll ein JPEG-Bild direkt in eine PDF-Datei eingebettet werden.
