Zeichnen
Geometrie
PDF verwendet die selbe Geometrie wie PostScript. Sie beginnt an der
linken unteren Ecke der Seite und wird in Punkten (1/72 Zoll) gemessen.
Die Seitengröße kann vom Seitenobjekt erhalten werden:
getWidth();
$height = $pdfPage->getHeight();
]]>
Farben
PDF bietet leistungsfähige Möglichkeiten für die Farbdarstellung. Die
Zend_Pdf Komponente unterstützt die Grauskala sowie RGB und CYMK
Farbräume. Jede kann überall verwendet werden, wo ein
Zend_Pdf_Color Objekt benötigt wird. Die
Zend_Pdf_Color_GrayScale,
Zend_Pdf_Color_Rgb und Zend_Pdf_Color_Cmyk
Klassen stellen folgende Funktionalitäten bereit:
Die HTML Farben werden auch durch die Klasse Zend_Pdf_Color_Html
bereitgestellt:
Zeichnen von Formen
Alle Zeichenoperationen können im Kontext einer PDF Seite
durchgeführt werden.
Die Zend_Pdf_Page Klass stellt einen Satz von einfachen Formen
bereit:
Zeichnen von Text
Auch alle Textoperationen können im Kontext einer PDF Seite
durchgeführt werden. Du kannst eine einzige Textzeile an jeder Position auf der Seite
durch Übergabe der X und Y Koordinaten für die Grundlinie zeichnen. Der aktuelle
Zeichensatz und die aktuelle Zeichengröße werden für die Textoperationen verwendet
(beachte die detaillierte Beschreibung unten).
Zeichne einen String auf der Seite
drawText('Hello world!', 72, 720);
...
]]>
Standardmäßig werden Textstrings unter Verwendung der Zeichenkodierungsmethode der
aktuelle "locale" interpretiert. Wenn du einen String hast, der eine andere
Zeichenkodierungsmethode verwendet (wie zum Beispiel ein UTF-8 String, der aus einer
Datei auf der Platte gelesen wurde, oder ein MacRoman String, der aus einer älteren
Datenbank erhalten wurde), kannst du die Zeichenkodierung zum Zeitpunkt des Zeichnens
angeben und Zend_Pdf wird die Konvertierung für dich durchführen.
Du kannst Quellstrings in jeder Kodierungsmethode übergeben, die von
PHP's iconv()
Funktion unterstützt wird.
Zeiche einen UTF-8 kodierten String auf der Seite
drawText($unicodeString, 72, 720, 'UTF-8');
...
]]>
Verwendung von Zeichensätzen
Zend_Pdf_Page::drawText() verwendet den aktuellen Zeichensatz
und die aktuelle Zeichengröße der Seite, die mit der Methode
Zend_Pdf_Page::setFont() festgelegt werden:
PDF Dokumente unterstützt PostScript Type1 und TrueType Zeichensätze,
sowie die zwei speziellen PDF Typen Type3 und zusammengesetzte
Zeichensätze (composite fonts). Es gibt zudem 14 Type1 Standardzeichensätze, die von
jedem PDF Viewer bereit gestellt werden: Courier (4 Stile), Helvetica
(4 Stile), Times (4 Stile), Symbol und Zapf Dingbats.
Die Zend_Pdf Komponente unterstützt derzeit diese 14
PDF Standardzeichensätze sowie deine eigenen TrueType Zeichensätze.
Zeichensatzobjekte können über eine der zwei Fabrikmethoden (factory methods) erhalten
werden: Zend_Pdf_Font::fontWithName($fontName) für die 14
PDF Standardzeichensätze oder
Zend_Pdf_Font::fontWithPath($filePath) für eigene Zeichensätze.
Einen Standardzeichensatz erstellen
setFont($font, 36);
...
]]>
Die Zeichensatzkonstanten für die 14 PDF Standardzeichensätze sind
innerhalb der Zend_Pdf_Font Klasse definiert:
Zend_Pdf_Font::FONT_COURIER
Zend_Pdf_Font::FONT_COURIER_BOLD
Zend_Pdf_Font::FONT_COURIER_ITALIC
Zend_Pdf_Font::FONT_COURIER_BOLDITALIC
Zend_Pdf_Font::FONT_TIMES_ROMAN
Zend_Pdf_Font::FONT_TIMES_BOLD
Zend_Pdf_Font::FONT_TIMES_ITALIC
Zend_Pdf_Font::FONT_TIMES_BOLDITALIC
Zend_Pdf_Font::FONT_HELVETICA
Zend_Pdf_Font::FONT_HELVETICA_BOLD
Zend_Pdf_Font::FONT_HELVETICA_ITALIC
Zend_Pdf_Font::FONT_HELVETICA_BOLDITALIC
Zend_Pdf_Font::FONT_SYMBOL
Zend_Pdf_Font::FONT_ZAPFDINGBATS
Du kannst außerdem jeden individuellen TrueType Zeichensatz (welcher normalerweise eine
'.ttf' Erweiterung hat) oder einen OpenType Zeichensatz ('.otf' Erweiterung) verwenden,
wenn er TrueType Konturen enthält. Bisher nicht unterstützt, aber für zukünftige
Versionen geplant, sind Mac OS X .dfont Dateien und Microsoft TrueType Collection
('.ttc' Erweiterung) Dateien.
Um einen TrueType Zeichensatz zu verwenden, mußt du den kompletten Verzeichnispfad zum
Zeichensatzprogramm angeben. Wenn der Zeichensatz aus welchem Grund auch immer nicht
gelesen werden kann oder wenn es kein TrueType Zeichensatz ist, wird the Fabrikmethode
eine Ausnahme werfen:
Einen TrueType Zeichensatz erstellen
setFont($goodDogCoolFont, 36);
...
]]>
Standardmäßig werden eigene Zeichensätze in das erstellte PDF
Dokument eingebettet. Dies ermöglicht den Empfänger, die Seite wie beabsichtigt
anzuschauen, sogar wenn sie den entsprechenden Zeichensatz auf ihrem System gar nicht
installiert haben. Wenn du dich über die Dateigröße sorgst, kannst du angeben, dass das
Zeichensatzprogramm nicht eingebettet wird, indem du eine 'nicht einbetten' Option an
die Fabrikmethode übergibst:
Erstelle einen TrueType Zeichensatz, aber bette ihn nicht in das PDF Dokument ein
setFont($goodDogCoolFont, 36);
...
]]>
Wenn das Zeichensatzprogramm nicht eingebettet wurde, aber den Empfänger der
PDF Datei diesen Zeichensatz auf seinem System installiert hat, wird
er das Dokument so sehen wie beabsichtigt. Wenn sie nicht den korrekten Zeichensatz
installiert haben, wird der PDF Viewer sich bemühen, um einen Ersatz
herzustellen.
Einige Zeichensätze haben sehr spezielle Lizensierungsregeln, die das Einbetten in
PDF Dokumente verhindern. Damit du dadurch nicht überrascht wirst,
wenn du versuchst einen Zeichensatz einzubetten, der nicht eingebettet werden kann,
wird die Fabrikmethode eine Ausnahme werfen.
Du kannst diese Zeichensätze weiterhin verwenden, aber du mußt entweder die 'nicht
einbetten' Option übergeben wie oben beschrieben oder du kannst einfach die Ausnahme
unterdrücken:
Werfe keine Ausnahme für Zeichensätze, die nicht eingebettet werden können
Diese Unterdrückungstechnik wird bevorzugt, wenn du einen Endnutzer erlaubst, seine
eigenen Zeichensätze auszuwählen. Zeichensätze, die in ein PDF
Dokument eingebettet werden können, werden eingebettet, andere nicht.
Zeichensatzprogramme können sehr groß sein, manche erreichen Dutzende von Megabytes.
Standardmäßig werden alle eingebetteten Zeichensätze unter Verwendung des Flate
Kompressionsschemas komprimiert, woraus im Schnitt 50% an Speicherplatz gespart werden
kann. Wenn du aus welchem Grund auch immer nicht möchtest, dass das Zeichensatzprogramm
kompimiert wird, kannst du dies mit einer Option abschalten:
Komprimiere einen eingebetten Zeichensatz nicht
Zuguterletzt, kannst du die Einbettungsoptionen mit Hilfe des OR Operators kombinieren,
wenn notwendig:
Kombiniere die Zeichensatz Einbettungsoptionen
Limits der Standard PDF Schriften
Die Standard PDF Schriften verwendetn intern verschiedene Single-Byte
Encodings (siehe PDF
Reference, Sixth Edition, version 1.7 Anhang D für Details). Diese sind
generell gleich wie beim Latin1 Zeichensatz (ausser den Symbol und ZapfDingbats
Schriften).
Zend_Pdf verwendet CP1252 (WinLatin1) für das Zeichnen von Text
mit Standardschriften.
Text kann trotzdem in jedem anderen Encoding angegeben werden, welches spezifiziert
werden muß wenn es sich vom aktuellen Gebietsschema unterscheidet. Nur WinLatin1 Zeichen
werden aktuell gezeichnet.
Kombinieren mit in Schriften enthaltenen Optionen
setFont($font, 36)
->drawText('Euro sign - €', 72, 720, 'UTF-8')
->drawText('Text with umlauts - à è ì', 72, 650, 'UTF-8');
...
]]>
Zeichnen von Grafiken
Die Zend_Pdf_Page Klasse stellt die drawImage() Methode für das
Zeichnen von Grafiken bereit:
Grafikobjekte sollten mit der Methode
Zend_Pdf_Image::imageWithPath($filePath) erzeugt werden. (Es
werden zur Zeit JPG, PNG und TIFF Grafiken unterstützt):
Zeichnen von Grafiken
drawImage($image, 100, 100, 400, 300);
...
]]>
Wichtig! JPG Support setzt voraus, dass die GD Erweiterung für
PHP konfiguriert wurde.
Wichtig! PNG Support setzt voraus, dass die ZLIB Erweiterung konfiguriert
wurde, um mit Grafiken mit Alphakanal zu arbeiten.
Wende dich an die PHP Dokumentation für weitere Informationen (http://www.php.net/manual/de/ref.image.php).
(http://www.php.net/manual/de/ref.zlib.php).
Stil der Strichzeichnungen
Der Stil der Strichzeichnungen wurd durch die Linienbreite, die Linienfarbe und das
Strichmuster definiert. Alle diese Parameter können an die Klassenmethoden von
Zend_Pdf_Page übergeben werden:
Füllstil
Die Methoden Zend_Pdf_Page::drawRectangle(),
Zend_Pdf_Page::drawPolygon(),
Zend_Pdf_Page::drawCircle() und
Zend_Pdf_Page::drawEllipse() akzeptieren das
$fillType Argument als optionalen Parameter. Es kann lauten:
Zend_Pdf_Page::SHAPE_DRAW_STROKE - strichele die Form
Zend_Pdf_Page::SHAPE_DRAW_FILL - fülle die Form
Zend_Pdf_Page::SHAPE_DRAW_FILL_AND_STROKE - fülle und strichele die Form
(Standardverhalten)
Die Zend_Pdf_Page::drawPolygon() Methode akzeptiert
$fillMethod als zusätzlichen Parameter:
Zend_Pdf_Page::FILL_METHOD_NON_ZERO_WINDING (Standardverhalten)
Die PDF Referenz beschreibt diese Regel wie folgt:
The nonzero winding number rule determines whether a given point is inside
a path by conceptually drawing a ray from that point to infinity in any
direction and then examining the places where a segment of the path crosses
the ray. Starting with a count of 0, the rule adds 1 each time a path
segment crosses the ray from left to right and subtracts 1 each time a
segment crosses from right to left. After counting all the crossings, if the
result is 0 then the point is outside the path; otherwise it is inside.
Note: The method just described does not specify what to do if a path
segment coincides with or is tangent to the chosen ray. Since the direction
of the ray is arbitrary, the rule simply chooses a ray that does not
encounter such problem intersections. For simple convex paths, the nonzero
winding number rule defines the inside and outside as one would intuitively
expect. The more interesting cases are those involving complex or
self-intersecting paths like the ones shown in Figure 4.10 (in a
PDF Reference).
For a path consisting of a five-pointed star, drawn with five connected
straight line segments intersecting each other, the rule considers the
inside to be the entire area enclosed by the star, including the pentagon in
the center. For a path composed of two concentric circles, the areas
enclosed by both circles are considered to be inside, provided that both are
drawn in the same direction. If the circles are drawn in opposite
directions, only the "doughnut" shape between them is inside, according to
the rule; the "doughnut hole" is outside.
Zend_Pdf_Page::FILL_METHOD_EVEN_ODD
Die PDF Referenz beschreibt diese Regel wie folgt:
An alternative to the nonzero winding number rule is the even-odd rule. This
rule determines the "insideness" of a point by drawing a ray from that point
in any direction and simply counting the number of path segments that cross
the ray, regardless of direction. If this number is odd, the point is
inside; if even, the point is outside. This yields the same results as the
nonzero winding number rule for paths with simple shapes, but produces
different results for more complex shapes.
Figure 4.11 (in a PDF Reference) shows the effects of
applying the even-odd rule to complex paths. For the five-pointed star, the
rule considers the triangular points to be inside the path, but not the
pentagon in the center. For the two concentric circles, only the "doughnut"
shape between the two circles is considered inside, regardless of the
directions in which the circles are drawn.
Lineare Transformationen
Drehungen
Bevor eine Zeichenoperation angewendet wird, können PDF Seiten
gedreht werden. Dies kann mit Hilfe der
Zend_Pdf_Page::rotate() Methode durchgeführt werden:
Beginnend mit ZF 1.8, Skalierung
Skalenänderungen werden durch die Zend_Pdf_Page::scale()
Methode angeboten:
Beginnend mit ZF 1.8, Bewegungen
Das bewegen des Koordinationssystem wird von der
Zend_Pdf_Page::translate() Methode durchgeführt:
Beginnend mit ZF 1.8, Drehungen
Das Drehen der Seite kann durch Verwendung der
Zend_Pdf_Page::skew() Methode durchgeführt werden:
Speichern/Wiederherstellen des Grafikzustand
Jederzeit kann der Grafikzustand der Seite (aktueller Zeichensatz, Schriftgröße,
Linienfarbe, Füllfarbe, Linienstil, Seitendrehung, Zeichenbereich) gespeichert und
wiederhergestellt werden. Speicheroperationen legen die Daten auf einen Grafikzustand
Stapel, Wiederherstelloperationen holen Sie daher zurück.
In der Zend_Pdf_Page Klasse gibt es für diese Operationen zwei
Methoden:
Zeichenbereich
PDF und die Zend_Pdf Komponente unterstützen
die Begrenzung des Zeichenbereichs. Der aktuelle Zeichenbereich begrenzt den
Seitenbereich, der von Zeichenoperationen beeinflusst werden kann. Zu Beginn ist dies
die gesamte Seite.
Die Zend_Pdf_Page Klasse stellt einen Satz von Methoden für die
Begrenzung bereit.
Stile
Die Zend_Pdf_Style Klasse stellt Stilfunktionalitäten bereit.
Stile können verwendet werden, um mit einer Operation die Parameter für den
Grafikzustand zu speichern und auf eine PDF Seite anzuwenden:
Die Zend_Pdf_Style Klasse stellt einen Satz von Methoden bereit,
um verschiedene Parameter des Grafikstadiums zu setzen und zu holen:
Transparenz
Das Zend_Pdf Modul unterstützt die Handhabung von Transparenz.
Transparenz kann durch Verwendung der Zend_Pdf_Page::setAlpha()
Methode gesetzt werden: