Archiv für den Monat: August 2008

Tutorial iTextSharp: Erstellen von PDF-Objekten

Texte

In iTextSharp werden Texte mithilfe von drei Klassen zusammengesetzt: Chunk, Phrase und Paragraph. Diese sollen in den nächsten Zeilen etwas näher beschrieben werden.

Chunk

Die Klasse Chunk befindet sich im Namespace iTextSharp.text. Chunk stellt die „kleinste“ Einheit in iTextSharp dar. Es besteht aus einem String, bei dem alle Zeichen die gleiche Formatierung (also Schriftart, -größe, -stil und -farbe) besitzen.

Chunk-Objekte besitzen keinerlei Informationen über Zeilenabstände. Das heißt, dass wenn der enthaltene String zu lang ist, wird ein Wagenrücklauf (Carriage return) ohne Zeilenvorschub ausgelöst. Das Resultat ist das, dass die gerade geschriebene Zeile überschrieben wird (ohne gelöscht zu werden). Deshalb sollten Chunk-Objekte in der Regel nicht dazu verwendet werden, direkt einem Dokument hinzugefügt zu werden. Stattdessen sollten sie in Kombination mit anderen Objekten verwendet werden.

Code-Beispiel

Document doc = new Document(PageSize.A4);
PdfWriter writer = PdfWriter.GetInstance(doc, File.Create(„Zitate.pdf“));
doc.Open();
Chunk zitatEinstein = new Chunk(„Phantasie ist wichtiger als Wissen, denn Wissen ist begrenzt.“);
Chunk zitatTwain = new Chunk(„Gib jedem Tag die Chance, der schönste deines Lebens zu werden.“);
doc.Add(zitatEinstein);
doc.Add(zitatTwain);
doc.Close();

Ausgabe im Adobe Reader

image

Phrase

Ein Phrase-Objekt (engl. Satz) besteht aus einer Aneinanderreihung von Chunk-Objekten mit einem wichtigen Extra: Wenn ein Zeilenende erkannt wird, dann wird neben den Wagenrücklauf (Carriage Return) auch ein Zeilenvorschub (New Line / Line Feed) ausgelöst, sodass sich die Chunks nicht mehr überschreiben. Der Zeilenabstand wird auch als Leading bezeichnet und kann im Konstruktor als auch in der Leading-Eigenschaft der Phrase-Klasse als float-Wert angegeben werden.

Zusätzlich ist es möglich, eine Hauptschriftart anzugeben, mit der das Phrase-Objekt formatiert wird. Somit erhalten alle enthaltenen Chunk-Objekte die gleiche Formatierung und ein einheitliches Aussehen. Aber ebenso kann man auch jedes Chunk-Objekt einzeln formatieren.

Code-Beispiel

Document doc = new Document(PageSize.A4);
PdfWriter writer = PdfWriter.GetInstance(doc, File.Create(„Zitate.pdf“));
doc.Open();
Chunk zitatEinstein = new Chunk(„Phantasie ist wichtiger als Wissen, denn Wissen ist begrenzt.“);
Chunk zitatTwain = new Chunk(„Gib jedem Tag die Chance, der schönste deines Lebens zu werden.“);
Phrase zitate = new Phrase(25);
zitate.Add(zitatEinstein);
zitate.Add(zitatTwain);
doc.Add(zitate);
doc.Close();

Ausgabe im Adobe Reader

image

Paragraph

Das Paragraph-Objekt verbindet mehrere Chunk- und Phrase-Objekte zu einem Absatz (Paragraph, engl. Absatz). Nach jedem Absatz wird automatisch ein Zeilenumbruch erstellt. Das entspricht etwa dem, dass man einem Phrase-Objekt ein Chunk.NEWLINE oder new Chunk(„n“) anhängt.

Die Paragraph-Klasse leitet von der Phrase-Klasse ab und ergänzt diese um einige Funktionen:

image

Abbildung 3: Klassenhierarchie bei Phrase und Paragraph

Der Zusammenhang zwischen Chunk, Phrase und Paragraph soll in folgender Abbildung verdeutlicht werden:

Bild1

Abbildung 4: Zusammenhang zwischen Paragraph, Phrase und Chunk

Initialisierung

Die Paragraph-Klasse besitzt mehrere Konstruktoren:

public Paragraph()
public Paragraph(float leading)
public Paragraph(Chunk chunk)
public Paragraph(float leading, Chunk chunk)
public Paragraph(string str)
public Paragraph(string str, Font font)
public Paragraph(float leading, string str)
public Paragraph(float leading, string str, Font font)
public Paragraph(Phrase phrase)

Ein Absatz kann also aus Chunks, Phrases oder String-Objekten erstellt werden. Über das Font-Objekt kann eine beliebige Schriftart für den Absatz festgelegt werden.

Abstand zwischen den Zeilen festlegen

Zusätzlich unterstützen einige Konstruktoren die Definition von Zeilenabständen (hier leading genannt). Alternativ kann über die Leading-Eigenschaft der Zeilenabstand festgelegt werden.

Abstand zwischen Absätzen festlegen

Den Abstand zwischen einzelnen Absätzen kann über die Eigenschaften SpacingBefore und SpacingAfter gesteuert werden. Dabei wird der angegebene Wert zu dem Wert addiert, der als leading definiert wurde.

Ausrichtung

Als „Besonderheit“ beim Paragraph-Objekt ist die Möglichkeit, Textausrichtungen vorzunehmen. Dazu wird die Methode SetAlignment verwendet. Als Parameter wird ein String erwartet, der als Konstante in ElementTag-Klasse festgelegt ist. Mögliche Werte sind: ALIGN_LEFT, ALIGN_CENTER, ALIGN_RIGHT, ALIGN_JUSTIFIED, ALIGN_JUSTIFIED_ALL, ALIGN_TOP, ALIGN_MIDDLE, ALIGN_BOTTOM und ALIGN_BASELINE.

Ebenso wäre es möglich, anstatt die SetAlignment-Methode zu verwenden, der Alignment-Eigenschaft einen Wert zuzuweisen. Dieser Wert muss dabei vom Typ integer sein. Auch hier gibt es wieder Konstanten, die zum Setzen der richtigen Ausrichtung verwendet werden – allerdings sind sie in der Element-Klasse definiert: ALIGN_LEFT, ALIGN_CENTER, ALIGN_RIGHT, ALIGN_JUSTIFIED, ALIGN_JUSTIFIED_ALL, ALIGN_TOP, ALIGN_MIDDLE, ALIGN_BOTTOM und ALIGN_BASELINE.

Wann man welche Methode verwendet, ist reine Geschmackssache. Intern wird SetAlignment auf Alignment gemappt.

Nachfolgend ein paar Code-Beispiele für die Textausrichtung im Absatz:

Document doc = new Document(PageSize.A4);
PdfWriter writer = PdfWriter.GetInstance(doc, File.Create(„Zitate.pdf“));
doc.Open();
Chunk zitatTwain = new Chunk(„Gib jedem Tag die Chance, der schönste deines Lebens zu werden.“);
zitatTwain.Font = FontFactory.GetFont(„Tahoma“, 24);
Paragraph paragraphTwain = new Paragraph(zitatTwain);

Setzen der Ausrichtung über SetAlignment-Methode

paragraphTwain.SetAlignment(ElementTags.ALIGN_CENTER);
doc.Add(paragraphTwain);
paragraphTwain.SetAlignment(ElementTags.ALIGN_LEFT);

Setzen der Ausrichtung über Alignment-Eigenschaft

doc.Add(paragraphTwain);
paragraphTwain.Alignment = Element.ALIGN_RIGHT;
doc.Add(paragraphTwain);
doc.Close();

Ausgabe im PDF

image

Einrückungen am Absatzanfang

Weiterhin besitzt das Paragraph-Objekt noch die Möglichkeit, Einrückungen am Anfang eines Absatzes einzufügen. Die wird mithilfe der IdentationLeft- und IdentationRight-Eigenschaft.

Tutorial iTextSharp: Writer & Meta-Daten

Das Writer-Objekt

Nachdem nun das Document-Objekt definiert wurde, wird zum Schreiben ein Writer-Objekt benötigt. Dieses entscheidet, wie das Dokument später geschrieben wird. Für jeden „Dokumenttyp“ gibt es ein Writer-Objekt: Beispielsweise wird für PDF-Dokumente ein PdfWriter benötigt, während für TeX-Dokumente ein TeXWriter instanziiert werden muss usw. Das Konzept von iTextSharp ermöglicht auch eine Dokumenttypen und –writer zu erstellen. Diese müssen nur von der abstrakten Klasse DocWriter aus dem iTextSharp.text-Namespace abgeleitet sein.

image

Abbildung 1: Klassenhierarchie DocWriter

Der Konstruktor der Writer-Klassen ist nicht öffentlich (private), sodass mittels GetInstance-Methode ein neues Objekt erzeugt werden muss. GetInstance erwartet zwei Parameter: das Document-Objekt (Das Document-Objekt) und einen Stream, in den die Ausgabe geschrieben wird.

Beispiel für das Erstellen eines neuen PDF-Writers:

Document doc = new Document(PageSize.A4.Rotate());

PdfWriter writer = PdfWriter.GetInstance(doc, File.Create(„test.pdf“));

Zum Schreiben einer PDF-Datei wird das writer-Objekt nicht mehr direkt verwendet (natürlich hält jedes Writer-Objekt einen IDocListener auf das Document-Objekt und wird somit über Änderungen im Document informiert). Stattdessen ermöglicht es weitere Features, auf die in den entsprechenden Kapiteln eingegangen wird:

  • Bearbeiten vorhandener PDF-Dokumente
  • Direktes Zeichnen von Grafiken
  • Verschlüsseln von PDF-Dokumenten
  • Viewer-Einstellungen vornehmen (Anzeige mit/ohne Menüleiste, Vollbild-Modus, Vorschaubilder anzeigen, Seiten-Skalierung etc.)
  • Dateien anhängen

PDF Meta-Daten bearbeiten

Die Meta-Daten im PDF-Dokument beinhalten allgemeine Informationen über das Dokument. Im Adobe Acrobat Reader können die Meta-Daten in den Dokumenteigenschaften (Datei à Dokumenteigenschaften / Strg + D) angesehen werden:

image

Abbildung 2: PDF-Metadaten

Rot hervorgehoben sind die jeweiligen Metadaten, die programmatisch auf dem Document-Objekt gesetzt werden können:

Eigenschaft in den Metadaten

image

Beispiel für das Setzen der Meta-Daten:

doc.AddAuthor(„Ralf Abramowitsch“);
doc.AddCreationDate();
doc.AddCreator(„Mein Tool“);
doc.AddKeywords(„iTextSharp“);
doc.AddKeywords(„Tutorial“);
doc.AddKeywords(„.NET“);
doc.AddSubject(„Thema“);
doc.AddTitle(„Titel“);
doc.AddProducer();

Tutorial iTextSharp: Einführung

iTextSharp ist eine Open Source Bibliothek zum Erstellen und Bearbeiten von PDF-Dateien. Die Java-Bibliothek iText wurde auf .NET (C#) portiert und wird synchron mit dem .NET-Pendant weiterentwickelt.

Ziel der Entwicklung war Entwicklern eine Bibliothek in die Hand zu geben, mit der sie ihre eigenen Anwendungen um PDF-Funktionalitäten erweitern konnten. In diesem Tutorial soll darum gehen, einzelne Funktionalitäten von iTextSharp anhand von Beispielen vorzustellen.

Bezugsmöglichkeiten

iText: http://www.lowagie.com/iText

iTextSharp: http://sourceforge.net/projects/itextsharp/

Tipp: Code-Dokumentation mit Doxygen erzeugen

Ich habe mich immer gefragt, warum ich denn bei IntelliSense keine Hilfe zu sehen bekomme. Ist der Code schlecht oder gar nicht dokumentiert? Nein! Der Autor hat darauf verzichtet, Kommentare im .NET-Format zu verfassen, stattdessen hat er auf das Doxygen-Format zurückgegriffen.

Somit werden keine Kommentare in die Metadaten exportiert und IntelliSense kann diese nicht auslesen. Daher ist jeder gut beraten, sich die Dokumentation kurz selbst zu erzeugen. Dazu lädt man einfach das letzte Doxygen Release von http://www.stack.nl/~dimitri/doxygen/ herunter.

Erstellen von PDF-Dokumenten

Das Document-Objekt

Das Document-Objekt stellt die Basis aller Dokument-Typen der iTextSharp-Bibliothek dar. Das Document-Objekt besitzt drei öffentliche Konstruktoren:

public Document()

public Document(Rectangle pageSize)

public Document(Rectangle pageSize, int marginLeft,int marginRight,

int marginTop, int marginBottom)

Definition der Seitengröße

Der parameterlose Konstruktor von Document verwendet als Default-Einstellung die Seitengröße A4, während die anderen beiden Konstruktoren eine Angabe der Seitengröße erwarten. Bei deren Definition kann auf die Klasse PageSize zurückgegriffen werden. PageSize besitzt öffentliche Felder, die die Auswahl von Seitengrößen vereinfacht. Mögliche Werte sind: A0 … A10, B0 … B10, HALFLETTER, LETTER, EXECUTIVE, LEGAL, NOTE, POSTCARD und einige mehr.

Definition des Seitenformats

Neben der eigentlichen Größe des PDF-Dokuments kann man auch dessen Ausrichtung, also Hochformat oder Querformat festlegen. Die Standard-Einstellung ist dabei Hochformat. Um eine Seite im Querformat anzulegen, ruft man einfach die Methode „rotate()“ auf dem von PageSize zurückgegebenen Wert auf. Ein PDF-Dokument im Querformat der Größe A4 würde wie folgt definiert werden:

Document doc = new Document(PageSize.A4.Rotate());

Definition der Seitenränder

Der dritte Konstruktor von Document bietet zudem noch die Möglichkeit, die Größe von Seitenrändern zu definieren. Die Angabe der Größe erfolgt in der Einheit „Point“ (Punkte). Die Umrechnung von „Point“ in „Zentimeter“ ist etwas umständlich, da die 72 Points genau ein Zoll darstellt. Ein Zoll wiederum besteht aus 2,54cm. Seitenränder von jeweils 2cm entsprechen also 56,693Points und werden wie folgt berechnet:

Ein PDF-Dokument der Seitengröße A4 mit jeweils 2cm Seitenrändern würde so erstellt werden:

Document doc = new Document(PageSize.A4.Rotate(), 28, 28, 28, 28);

image

Öffnen und Schließen des Documents

Document besitzt zwei wesentliche Funktionen, die zum Erstellen des PDF-Dokuments notwendig sind: Open() und Close():

Open() / IsOpen()
Um ein Dokument zu bearbeiten bzw. mit Inhalten zu befüllen, muss es geöffnet werden. Dazu ruft man die Methode Open() auf dem Document-Objekt auf. Über die Methode IsOpen() kann man abfragen, ob das Dokument bereits mit Open() geöffnet wurde.
Hinweis: Nachdem Open() aufgerufen wurde, kann man weder Meta-Daten noch PDF-Header-Informationen bearbeiten!

Close()
Sobald alle Inhalte dem Dokument hinzugefügt wurden, muss das Dokument geschlossen werden, damit es korrekt (auf die Festplatte) geschrieben werden kann. Nach dem Aufruf von Close() kann nichts mehr hinzugefügt werden.

Vortrag: iTextSharp – Eigene Programme um PDF-Funktionalität erweitern

Am Mittwoch, den 30. Juli 2008, habe ich vor der .NET-Developers Group Stuttgart einen Vortrag über die Open Source Bibliothek iTextSharp gehalten.

Den Vortrag, zusammen mit Code-Beispielen, habe ich auf meinen Webserver hochgeladen: www.abramowitsch.de/vortraege/dotnetstuttgart/itextsharp/itextsharp.zip

Viel Spaß damit 🙂

Ralf