repo_zf1/documentation/manual/de/module_specs/Zend_Pdf-Drawing.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 15157 -->
<!-- Reviewed: no -->
<sect1 id="zend.pdf.drawing">
    <title>Zeichnen</title>

    <sect2 id="zend.pdf.drawing.geometry">
        <title>Geometrie</title>
        <para>
            PDF verwendet die selbe Geometrie wie PostScript. Sie beginnt an der linken unteren
            Ecke der Seite und wird in Punkten (1/72 Zoll) gemessen.
        </para>
        <para>
            Die Seitengröße kann vom Seitenobjekt erhalten werden:
        </para>
            <programlisting role="php"><![CDATA[
$width  = $pdfPage->getWidth();
$height = $pdfPage->getHeight();
]]></programlisting>
    </sect2>

    <sect2 id="zend.pdf.drawing.color">
        <title>Farben</title>
        <para>
            PDF bietet leistungsfähige Möglichkeiten für die Farbdarstellung. Die <classname>Zend_Pdf</classname>
            Komponente unterstützt die Grauskala sowie RGB und CYMK Farbräume. Jede kann überall
            verwendet werden, wo ein <classname>Zend_Pdf_Color</classname> Objekt benötigt wird. Die
            <classname>Zend_Pdf_Color_GrayScale</classname>, <classname>Zend_Pdf_Color_Rgb</classname> und
            <classname>Zend_Pdf_Color_Cmyk</classname> Klassen stellen folgende Funktionalitäten bereit:
        </para>
            <programlisting role="php"><![CDATA[
// $grayLevel (Fließkommazahl). 0.0 (schwarz) - 1.0 (weiß)
$color1 = new Zend_Pdf_Color_GrayScale($grayLevel);

// $r, $g, $b (Fließkommazahlen). 0.0 (min Helligkeit) - 1.0 (max Helligkeit)
$color2 = new Zend_Pdf_Color_Rgb($r, $g, $b);

// $c, $m, $y, $k (Fließkommazahlen). 0.0 (min Helligkeit) - 1.0 (max Helligkeit)
$color3 = new Zend_Pdf_Color_Cmyk($c, $m, $y, $k);
]]></programlisting>

        <para>
        HTML style colors are also provided with <classname>Zend_Pdf_Color_Html</classname> class:
        </para>
        <programlisting role="php"><![CDATA[
$color1 = new Zend_Pdf_Color_Html('#3366FF');
$color2 = new Zend_Pdf_Color_Html('silver');
$color3 = new Zend_Pdf_Color_Html('forestgreen');
]]></programlisting>
    </sect2>

    <sect2 id="zend.pdf.drawing.shape-drawing">
        <title>Zeichnen von Formen</title>
        <para>
            Alle Zeichenoperationen können im Kontext einer PDF Seite durchgeführt werden.
        </para>
        <para>
            Die <classname>Zend_Pdf_Page</classname> Klass stellt einen Satz von einfachen Formen bereit:
        </para>
        <programlisting role="php"><![CDATA[
/**
 * Zeichne eine Linie von x1,y1 nach x2,y2.
 *
 * @param float $x1
 * @param float $y1
 * @param float $x2
 * @param float $y2
 * @return Zend_Pdf_Page
 */
public function drawLine($x1, $y1, $x2, $y2);
]]></programlisting>
        <programlisting role="php"><![CDATA[
/**
 * Zeichne ein Rechteck.
 *
 * Füllarten:
 * Zend_Pdf_Page::SHAPE_DRAW_FILL_AND_STROKE - fülle und strichliere
 *                                             das Rechteck (Standard)
 * Zend_Pdf_Page::SHAPE_DRAW_STROKE          - strichele das Rechteck
 * Zend_Pdf_Page::SHAPE_DRAW_FILL            - fülle das Rechteck
 *
 * @param float $x1
 * @param float $y1
 * @param float $x2
 * @param float $y2
 * @param integer $fillType
 * @return Zend_Pdf_Page
 */
public function drawRectangle($x1, $y1, $x2, $y2,
                    $fillType = Zend_Pdf_Page::SHAPE_DRAW_FILL_AND_STROKE);
]]></programlisting>
        <programlisting role="php"><![CDATA[
/**
 * Zeichne ein Polygon
 *
 * Wenn $fillType Zend_Pdf_Page::SHAPE_DRAW_FILL_AND_STROKE oder
 * Zend_Pdf_Page::SHAPE_DRAW_FILL ist, wird das Polygon automatisch geschlossen.
 * Für eine detaillierte Beschreibung dieser Methode schaue in eine PDF Dokumentation
 * (Kapitel 4.4.2 Path painting Operators, Filling)
 *
 * @param array $x  - Array mit Floats (die X Koordinaten der Eckpunkte)
 * @param array $y  - Array mit Floats (the Y Koordinaten der Eckpunkte)
 * @param integer $fillType
 * @param integer $fillMethod
 * @return Zend_Pdf_Page
 */
public function drawPolygon($x, $y,
                            $fillType =
                                Zend_Pdf_Page::SHAPE_DRAW_FILL_AND_STROKE,
                            $fillMethod =
                                Zend_Pdf_Page::FILL_METHOD_NON_ZERO_WINDING);
]]></programlisting>
        <programlisting role="php"><![CDATA[
/**
 * Zeichne einen Kreis mit dem Mittelpunkt x, y dem Radius radius.
 *
 * Winkel werden im Bogenmaß angegeben
 *
 * Methoden Signaturen:
 * drawCircle($x, $y, $radius);
 * drawCircle($x, $y, $radius, $fillType);
 * drawCircle($x, $y, $radius, $startAngle, $endAngle);
 * drawCircle($x, $y, $radius, $startAngle, $endAngle, $fillType);
 *
 *
 * Es ist kein echter Kreis, weil PDF nur kubische Bezierkurven
 * unterstützt. Aber es ist eine sehr Annäherung.
 * Es unterscheidet sich von echten Kreisen maximal um 0.00026 Radien
 * (Bei PI/8, 3*PI/8, 5*PI/8, 7*PI/8, 9*PI/8, 11*PI/8, 13*PI/8 und
 * 15*PI/8 Winkeln). Bei 0, PI/4, PI/2, 3*PI/4, PI, 5*PI/4, 3*PI/2 und
 * 7*PI/4 ist es exakt eine Tangente zu einem Kreis.
 *
 * @param float $x
 * @param float $y
 * @param float $radius
 * @param mixed $param4
 * @param mixed $param5
 * @param mixed $param6
 * @return Zend_Pdf_Page
 */
public function  drawCircle($x,
                            $y,
                            $radius,
                            $param4 = null,
                            $param5 = null,
                            $param6 = null);
]]></programlisting>
        <programlisting role="php"><![CDATA[
/**
 * Zeichne eine Ellipse innerhalb des angegebenen Rechtecks.
 *
 * Methoden Signaturen:
 * drawEllipse($x1, $y1, $x2, $y2);
 * drawEllipse($x1, $y1, $x2, $y2, $fillType);
 * drawEllipse($x1, $y1, $x2, $y2, $startAngle, $endAngle);
 * drawEllipse($x1, $y1, $x2, $y2, $startAngle, $endAngle, $fillType);
 *
 * Winkel werden im Bogenmaß angegeben
 *
 * @param float $x1
 * @param float $y1
 * @param float $x2
 * @param float $y2
 * @param mixed $param5
 * @param mixed $param6
 * @param mixed $param7
 * @return Zend_Pdf_Page
 */
public function drawEllipse($x1,
                            $y1,
                            $x2,
                            $y2,
                            $param5 = null,
                            $param6 = null,
                            $param7 = null);
]]></programlisting>
    </sect2>

    <sect2 id="zend.pdf.drawing.text-drawing">
        <title>Zeichnen von Text</title>
        <para>
            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).
        </para>
        <programlisting role="php"><![CDATA[
/**
 * Zeichne eine Textzeile an einer bestimmten Position.
 *
 * @param string $text
 * @param float $x
 * @param float $y
 * @param string $charEncoding (optional) Zeichencodierung des
 *               Quelltexts. Standard ist die aktuelle "locale".
 * @throws Zend_Pdf_Exception
 * @return Zend_Pdf_Page
 */
public function drawText($text, $x, $y, $charEncoding = '');
]]></programlisting>
        <example id="zend.pdf.drawing.text-drawing.example-1">
            <title>Zeichne einen String auf der Seite</title>
            <programlisting role="php"><![CDATA[
...
$pdfPage->drawText('Hello world!', 72, 720);
...
]]></programlisting>
        </example>
        <para>
            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 <classname>Zend_Pdf</classname> wird die Konvertierung für dich durchführen. Du kannst Quellstrings
            in jeder Kodierungsmethode übergeben, die von PHP's
            <code><ulink url="http://www.php.net/manual/function.iconv.php">iconv()</ulink></code>
            Funktion unterstützt wird.
        </para>
        <example id="zend.pdf.drawing.text-drawing.example-2">
            <title>Zeiche einen UTF-8 kodierten String auf der Seite</title>
            <programlisting role="php"><![CDATA[
...
// Lese einen UTF-8 kodierten String von der Platte
$unicodeString = fread($fp, 1024);

// Zeichne den String auf der Seite
$pdfPage->drawText($unicodeString, 72, 720, 'UTF-8');
...
]]></programlisting>
        </example>
    </sect2>

    <sect2 id="zend.pdf.drawing.using-fonts">
        <title>Verwendung von Zeichensätzen</title>
        <para>
            <classname>Zend_Pdf_Page::drawText()</classname> verwendet den aktuellen Zeichensatz und die
            aktuelle Zeichengröße der Seite, die mit der Methode <classname>Zend_Pdf_Page::setFont()</classname>
            festgelegt werden:
        </para>
            <programlisting role="php"><![CDATA[
/**
 * Lege den aktuellen Zeichensatz fest.
 *
 * @param Zend_Pdf_Resource_Font $font
 * @param float $fontSize
 * @return Zend_Pdf_Page
 */
public function setFont(Zend_Pdf_Resource_Font $font, $fontSize);
]]></programlisting>
        <para>
            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.
        </para>
        <para>
            Die <classname>Zend_Pdf</classname> Komponente unterstützt derzeit diese 14 Standardzeichensätze sowie deine
            eigenen TrueType Zeichensätze. Zeichensatzobjekte können über eine der zwei
            Fabrikmethoden (factory methods) erhalten werden:
            <classname>Zend_Pdf_Font::fontWithName($fontName)</classname> für die 14 PDF Standardzeichensätze
            oder <classname>Zend_Pdf_Font::fontWithPath($filePath)</classname> für eigene Zeichensätze.
        </para>
        <example id="zend.pdf.drawing.using-fonts.example-1">
            <title>Erstelle einen Standardzeichensatz</title>
            <programlisting role="php"><![CDATA[
...
// Erstelle einen neuen Zeichensatz
$font = Zend_Pdf_Font::fontWithName(Zend_Pdf_Font::FONT_HELVETICA);

// Wende Zeichensatz an
$pdfPage->setFont($font, 36);
...
]]></programlisting>
        </example>
        <para>
            Die Zeichensatzkonstanten für die 14 Standardzeichensätze sind innerhalb der
            <classname>Zend_Pdf_Font</classname> Klasse definiert:
        <itemizedlist>
            <listitem>
                <para>Zend_Pdf_Font::FONT_COURIER</para>
            </listitem>
            <listitem>
                <para>Zend_Pdf_Font::FONT_COURIER_BOLD</para>
            </listitem>
            <listitem>
                <para>Zend_Pdf_Font::FONT_COURIER_ITALIC</para>
            </listitem>
            <listitem>
                <para>Zend_Pdf_Font::FONT_COURIER_BOLDITALIC</para>
            </listitem>
            <listitem>
                <para>Zend_Pdf_Font::FONT_TIMES_ROMAN</para>
            </listitem>
            <listitem>
                <para>Zend_Pdf_Font::FONT_TIMES_BOLD</para>
            </listitem>
            <listitem>
                <para>Zend_Pdf_Font::FONT_TIMES_ITALIC</para>
            </listitem>
            <listitem>
                <para>Zend_Pdf_Font::FONT_TIMES_BOLDITALIC</para>
            </listitem>
            <listitem>
                <para>Zend_Pdf_Font::FONT_HELVETICA</para>
            </listitem>
            <listitem>
                <para>Zend_Pdf_Font::FONT_HELVETICA_BOLD</para>
            </listitem>
            <listitem>
                <para>Zend_Pdf_Font::FONT_HELVETICA_ITALIC</para>
            </listitem>
            <listitem>
                <para>Zend_Pdf_Font::FONT_HELVETICA_BOLDITALIC</para>
            </listitem>
            <listitem>
                <para>Zend_Pdf_Font::FONT_SYMBOL</para>
            </listitem>
            <listitem>
                <para>Zend_Pdf_Font::FONT_ZAPFDINGBATS</para>
            </listitem>
        </itemizedlist>
        </para>
        <para>
            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.
        </para>
        <para>
            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:
        </para>
        <example id="zend.pdf.drawing.using-fonts.example-2">
            <title>Erstelle einen TrueType Zeichensatz</title>
            <programlisting role="php"><![CDATA[
...
// Erstelle einen neuen Zeichensatz
$goodDogCoolFont = Zend_Pdf_Font::fontWithPath('/path/to/GOODDC__.TTF');

// Verwende den Zeichensatz
$pdfPage->setFont($goodDogCoolFont, 36);
...
]]></programlisting>
        </example>
        <para>
            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:
        </para>
        <example id="zend.pdf.drawing.using-fonts.example-3">
            <title>Erstelle einen TrueType Zeichensatz, aber bette ihn nicht in das PDF Dokument ein.</title>
            <programlisting role="php"><![CDATA[
...
// Erstelle einen neuen Zeichensatz
$goodDogCoolFont = Zend_Pdf_Font::fontWithPath('/path/to/GOODDC__.TTF',
                                               Zend_Pdf_Font::EMBED_DONT_EMBED);

// Verwende den Zeichensatz
$pdfPage->setFont($goodDogCoolFont, 36);
...
]]></programlisting>
        </example>
        <para>
            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.
        </para>
        <para>
            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.
        </para>
        <para>
            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:
        </para>
        <example id="zend.pdf.drawing.using-fonts.example-4">
            <title>Werfe keine Ausnahme für Zeichensätze, die nicht eingebettet werden können.</title>
            <programlisting role="php"><![CDATA[
...
$font = Zend_Pdf_Font::fontWithPath(
           '/path/to/unEmbeddableFont.ttf',
           Zend_Pdf_Font::EMBED_SUPPRESS_EMBED_EXCEPTION
        );
...
]]></programlisting>
        </example>
        <para>
            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.
        </para>
        <para>
            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:
        </para>
        <example id="zend.pdf.drawing.using-fonts.example-5">
            <title>Komprimiere einen eingebetten Zeichensatz nicht.</title>
            <programlisting role="php"><![CDATA[
...
$font = Zend_Pdf_Font::fontWithPath('/path/to/someReallyBigFont.ttf',
                                    Zend_Pdf_Font::EMBED_DONT_COMPRESS);
...
]]></programlisting>
        </example>
        <para>
            Zuguterletzt, kannst du die Einbettungsoptionen mit Hilfe des OR Operators kombinieren,
            wenn notwendig:
        </para>
        <example id="zend.pdf.drawing.using-fonts.example-6">
            <title>Kombiniere die Zeichensatz Einbettungsoptionen.</title>
            <programlisting role="php"><![CDATA[
...
$font = Zend_Pdf_Font::fontWithPath(
            $someUserSelectedFontPath,
            (Zend_Pdf_Font::EMBED_SUPPRESS_EMBED_EXCEPTION |
            Zend_Pdf_Font::EMBED_DONT_COMPRESS));
...
]]></programlisting>
        </example>

    </sect2>

    <sect2 id="zend.pdf.drawing.standard-fonts-limitations">
        <title>Limits der Standard PDF Schriften</title>
        <para>
            Die Standard PDF Schriften verwendetn intern verschiedene Single-Byte Encodings (siehe
            <ulink url="http://www.adobe.com/devnet/acrobat/pdfs/pdf_reference_1-7.pdf">PDF Reference, Sixth Edition, version 1.7</ulink>
            Anhang D für Details). Diese sind generell gleich wie beim Latin1 Zeichensatz (ausser den Symbol und
            ZapfDingbats Schriften).
        </para>
        <para>
            <classname>Zend_Pdf</classname> verwendet CP1252 (WinLatin1) für das Zeichnen von Text mit Standardschriften.
        </para>
        <para>
            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.
        </para>
        <example id="zend.pdf.drawing.using-fonts.example-7">
            <title>Kombinieren mit in Schriften enthaltenen Optionen</title>
            <programlisting role="php"><![CDATA[
...
$font = Zend_Pdf_Font::fontWithName(Zend_Pdf_Font::FONT_COURIER);
$pdfPage->setFont($font, 36)
        ->drawText('Euro sign - €', 72, 720, 'UTF-8')
        ->drawText('Text with umlauts - à è ì', 72, 650, 'UTF-8');
...
]]></programlisting>
        </example>
    </sect2>

    <sect2 id="zend.pdf.drawing.extracting-fonts">
        <title>Schriften extrahieren</title>
        <para>
            Das <classname>Zend_Pdf</classname> Modul bietet die Möglichkeit Schriften von geladenen Dokumenten zu
            extrahieren.
        </para>

        <para>
            Das kann für aufsteigende Dokumenten Updates nützlich sein. Ohne diese Funktionalität müssen Schriften
            jedes Mal in ein Dokument hinzugefügt und möglicherweise eingebetten werden, wenn es aktualisiert
            werden soll.
        </para>

        <para>
            Die <classname>Zend_Pdf</classname> und <classname>Zend_Pdf_Page</classname> Objekte bieten spezielle Methoden um alle
            genannten Schriften innerhalb eines Dokuments oder einer Seite zu extrahieren:
        </para>
        <example id="zend.pdf.drawing.extracting-fonts.example-1">
            <title>Schriften von einem geladenen Dokument extrahieren</title>
            <programlisting role="php"><![CDATA[

...
$pdf = Zend_Pdf::load($documentPath);
...
// Alle Schriften des Dokuments bekommen
$fontList = $pdf->extractFonts();
$pdf->pages[] = ($page = $pdf->newPage(Zend_Pdf_Page::SIZE_A4));
$yPosition = 700;
foreach ($fontList as $font) {
    $page->setFont($font, 15);
    $fontName = $font->getFontName(Zend_Pdf_Font::NAME_POSTSCRIPT,
                                   'en',
                                   'UTF-8');
    $page->drawText($fontName . ': Der schnelle braune Fuchs springt '
                              . 'über den lahmen Hund',
                    100,
                    $yPosition,
                    'UTF-8');
    $yPosition -= 30;
}
...
// Alle Schriften die in der ersten Seite des Dokuments referenziert sind erhalten
$firstPage = reset($pdf->pages);
$firstPageFonts = $firstPage->extractFonts();
...
]]></programlisting>
        </example>
        <example id="zend.pdf.drawing.extracting-fonts.example-2">
            <title>Eine Schrift von einem geladenen Dokument extrahieren durch die Angabe des Schriftnamens</title>
            <programlisting role="php"><![CDATA[

...
$pdf = new Zend_Pdf();
...
$pdf->pages[] = ($page = $pdf->newPage(Zend_Pdf_Page::SIZE_A4));

$font = Zend_Pdf_Font::fontWithPath($fontPath);
$page->setFont($font, $fontSize);
$page->drawText($text, $x, $y);
...
// Diese Schrift sollte woanders gespeichert werden...
$fontName = $font->getFontName(Zend_Pdf_Font::NAME_POSTSCRIPT,
                               'en',
                               'UTF-8');
...
$pdf->save($docPath);
...
]]></programlisting>
            <programlisting role="php"><![CDATA[

...
$pdf = Zend_Pdf::load($docPath);
...
$pdf->pages[] = ($page = $pdf->newPage(Zend_Pdf_Page::SIZE_A4));

/* $srcPage->extractFont($fontName) kann auch hier verwendet werden */
$font = $pdf->extractFont($fontName);
$page->setFont($font, $fontSize);
$page->drawText($text, $x, $y);
...
$pdf->save($docPath, true /* aufsteigender Update Modus */);
...
]]></programlisting>
        </example>

        <para>
            Extrahierte Schriften können statt jeder anderen Schrift mit den folgenden Einschränkungen
            verwendet werden:
            <itemizedlist>
                <listitem><para>Eine extrahierte Schrift kann nur im Kontext des Dokuments verwendet werden
                von dem es extrahiert wurde.</para></listitem>
                <listitem>
                    <para>
                        Ein möglicherweise eingebettetes Schriftprogramm wird aktuell nicht extrahiert. Deswegen
                        können extrahierte Schriften keine richtigen Schriftmaße bieten und die originale
                        Schrift wird für die Berechnung der Breite verwendet:
            <programlisting role="php"><![CDATA[

...
$font = $pdf->extractFont($fontName);
$originalFont = Zend_Pdf_Font::fontWithPath($fontPath);

$page->setFont($font /* Die extrahierte Schrift für das Zeichnen verwenden */, $fontSize);
$xPosition = $x;
for ($charIndex = 0; $charIndex < strlen($text); $charIndex++) {
    $page->drawText($text[$charIndex], xPosition, $y);

    // Die originale Schrift für die Berechnung der Breite des Textes verwenden
    $width += $originalFont->widthForGlyph(
                  $originalFont->glyphNumberForCharacter($text[$charIndex])
              );
    $xPosition += $width/$originalFont->getUnitsPerEm()*$fontSize;
}
...
]]></programlisting>
                    </para>
                </listitem>
            </itemizedlist>
        </para>
    </sect2>

    <sect2 id="zend.pdf.drawing.image-drawing">
        <title>Zeichnen von Grafiken</title>
        <para>
            Die <classname>Zend_Pdf_Page</classname> Klasse stellt die drawImage() Methode für das Zeichnen
            von Grafiken bereit:
        </para>
        <programlisting role="php"><![CDATA[
/**
 * Zeichne eine Grafik an der angegebenen Position der Seite.
 *
 * @param Zend_Pdf_Ressource_Image $image
 * @param float $x1
 * @param float $y1
 * @param float $x2
 * @param float $y2
 * @return Zend_Pdf_Page
 */
public function drawImage(Zend_Pdf_Ressource_Image $image, $x1, $y1, $x2, $y2);
]]></programlisting>
        <para>
            Grafikobjekte sollten mit der Methode <classname>Zend_Pdf_Image::imageWithPath($filePath)</classname>
            erzeugt werden. (Es werden zur Zeit JPG, PNG und TIFF Grafiken unterstützt):
        </para>
        <example id="zend.pdf.drawing.image-drawing.example-1">
            <title>Zeichnen von Grafiken</title>
            <programlisting role="php"><![CDATA[
...
// Lade die Grafik
$image = Zend_Pdf_Image::imageWithPath('my_image.jpg');

$pdfPage->drawImage($image, 100, 100, 400, 300);
...
]]></programlisting>
        </example>

        <para>
            <emphasis>Wichtig! JPG Support setzt voraus, dass die GD Erweiterung für PHP konfiguriert wurde.</emphasis>
            <emphasis>Wichtig! PNG Support setzt voraus, dass die ZLIB Erweiterung konfiguriert wurde, um mit Grafiken
            mit Alphakanal zu arbeiten.</emphasis>
        </para>
        <para>
            Wende dich an die PHP Dokumentation für weitere Informationen
            (<ulink url="http://www.php.net/manual/de/ref.image.php">http://www.php.net/manual/de/ref.image.php</ulink>).
            (<ulink url="http://www.php.net/manual/de/ref.zlib.php">http://www.php.net/manual/de/ref.zlib.php</ulink>).
        </para>
    </sect2>

    <sect2 id="zend.pdf.drawing.line-drawing-style">
        <title>Stil der Strichzeichnungen</title>
        <para>
            Der Stil der Strichzeichnungen wurd durch die Linienbreite, die Linienfarbe und das
            Strichmuster definiert. Alle diese Parameter können an die Klassenmethoden von
            <classname>Zend_Pdf_Page</classname> übergeben werden:
        </para>
        <programlisting role="php"><![CDATA[
/** Setze die Linienfarbe. */
public function setLineColor(Zend_Pdf_Color $color);

/** Setze die Linienbreite. */
public function setLineWidth(float $width);

/**
 * Setze das Strichmuster.
 *
 * Pattern ist ein Array mit Fließkommazahlen:
 *     array(on_length, off_length, on_length, off_length, ...)
 * Phase is shift from the beginning of line.
 *
 * @param array $pattern
 * @param array $phase
 * @return Zend_Pdf_Page
 */
public function setLineDashingPattern($pattern, $phase = 0);
]]></programlisting>
    </sect2>

    <sect2 id="zend.pdf.drawing.fill-style">
        <title>Füllstil</title>
        <para>
            Die Methoden <classname>Zend_Pdf_Page::drawRectangle()</classname>,
            <classname>Zend_Pdf_Page::drawPolygon()</classname>, <classname>Zend_Pdf_Page::drawCircle()</classname> und
            <classname>Zend_Pdf_Page::drawEllipse()</classname> akzeptieren das <code>$fillType</code>
            Argument als optionalen Parameter. Es kann lauten:
        </para>

        <itemizedlist>
            <listitem>
                <para>Zend_Pdf_Page::SHAPE_DRAW_STROKE - strichele die Form</para>
            </listitem>
            <listitem>
                <para>Zend_Pdf_Page::SHAPE_DRAW_FILL - fülle die Form</para>
            </listitem>
            <listitem>
                <para>Zend_Pdf_Page::SHAPE_DRAW_FILL_AND_STROKE - fülle und strichele die Form
                (Standardverhalten)</para>
            </listitem>
        </itemizedlist>

        <para>
            Die <classname>Zend_Pdf_Page::drawPolygon()</classname> Methode akzeptiert
            <code>$fillMethod</code> als zusätzlichen Parameter:
        </para>
        <itemizedlist>
            <listitem>
                <para>Zend_Pdf_Page::FILL_METHOD_NON_ZERO_WINDING (Standardverhalten)</para>
                <para>
                    <citetitle>Die PDF Referenz</citetitle> beschreibt diese Regel wie folgt:
                    <blockquote>
                    <para>
                        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.
                    </para>
                    </blockquote>
                </para>
            </listitem>
            <listitem>
                <para>Zend_Pdf_Page::FILL_METHOD_EVEN_ODD</para>
                <para>
                    <citetitle>Die PDF Referenz</citetitle> beschreibt diese Regel wie folgt:
                    <blockquote>
                    <para>
                        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.
                    </para>
                </blockquote>
            </para>
            </listitem>
        </itemizedlist>
    </sect2>

    <sect2 id="zend.pdf.drawing.linear-transformations">
        <title>Lineare Transformationen</title>
        <sect3 id="zend.pdf.drawing.linear-transformations.rotations">
            <title>Drehungen</title>
            <para>
                Bevor eine Zeichenoperation angewendet wird, können PDF Seiten gedreht werden. Dies
                kann mit Hilfe der <classname>Zend_Pdf_Page::rotate()</classname> Methode durchgeführt werden:
            </para>
            <programlisting role="php"><![CDATA[
/**
 * Drehe die Seite
 *
 * @param float $x - die X Koordinate des Rotationspunktes
 * @param float $y - die Y Koordinate des Rotationspunktes
 * @param float $angle - der Rotationswinkel
 * @return Zend_Pdf_Page
 */
public function rotate($x, $y, $angle);
]]></programlisting>
        </sect3>

        <sect3 id="zend.pdf.drawing.linear-transformations.scale">
            <title>Beginnend mit ZF 1.8, Skalierung</title>
            <para>
                Skalenänderungen werden durch die <classname>Zend_Pdf_Page::scale()</classname> Methode angeboten:
            </para>
            <programlisting role="php"><![CDATA[
/**
 * Koordinationssystem für die Skala
 *
 * @param float $xScale - Skalierungsfaktor für die X Dimension
 * @param float $yScale - Skalierungsfaktor für die Y Dimension
 * @return Zend_Pdf_Page
 */
public function scale($xScale, $yScale);
]]></programlisting>
        </sect3>

        <sect3 id="zend.pdf.drawing.linear-transformations.translate">
            <title>Beginnend mit ZF 1.8, Bewegungen</title>
            <para>
                Das bewegen des Koordinationssystem wird von der <classname>Zend_Pdf_Page::translate()</classname>
                Methode durchgeführt:
            </para>
            <programlisting role="php"><![CDATA[
/**
 * Bewegen des Koordinationssystems
 *
 * @param float $xShift - X Koordinate für die Bewegung
 * @param float $yShift - Y Koordinate für die Bewegung
 * @return Zend_Pdf_Page
 */
public function translate($xShift, $yShift);
]]></programlisting>
        </sect3>

        <sect3 id="zend.pdf.drawing.linear-transformations.skew">
            <title>Beginnend mit ZF 1.8, Drehungen</title>
            <para>
                Das Drehen der Seite kann durch Verwendung der <classname>Zend_Pdf_Page::skew()</classname> Methode
                durchgeführt werden:
            </para>
            <programlisting role="php"><![CDATA[
/**
 * Bewegen des Koordinationssystems
 *
 * @param float $x  - Die X Koordinate des Achsen-Drehpunktes
 * @param float $y  - Die Y Koordinate des Achsen-Drehpunktes
 * @param float $xAngle - X Winkel der Achse
 * @param float $yAngle - Y Winkel der Achse
 * @return Zend_Pdf_Page
 */
public function skew($x, $y, $xAngle, $yAngle);
]]></programlisting>
        </sect3>
    </sect2>

    <sect2 id="zend.pdf.drawing.save-restore">
        <title>Speichern/Wiederherstellen des Grafikzustand</title>
        <para>
            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.
        </para>
        <para>
            In der <classname>Zend_Pdf_Page</classname> Klasse gibt es für diese Operationen zwei Methoden:
        </para>
        <programlisting role="php"><![CDATA[
/**
 * Speichere den Grafikzustand dieser Seite.
 * Es wir ein Schnappschuss vom aktuell festgelegten Stil, Position,
 * Zeichenbereich und jeder festgelegten Drehung/Umrechnung/Skalierung
 * erstellt.
 *
 * @return Zend_Pdf_Page
 */
public function saveGS();

/**
 * Stelle den Grafikzustand wieder her, der mit dem letzten Aufruf von
 * saveGS() gespeichert wurde
 *
 * @return Zend_Pdf_Page
 */
public function restoreGS();
]]></programlisting>
    </sect2>

    <sect2 id="zend.pdf.drawing.clipping">
        <title>Zeichenbereich</title>
        <para>
            PDF und die <classname>Zend_Pdf</classname> 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.
        </para>
        <para>
            Die <classname>Zend_Pdf_Page</classname> Klasse stellt einen Satz von Methoden für die Begrenzung
            bereit.
        </para>
        <programlisting role="php"><![CDATA[
/**
 * Durchschneide den aktuellen Zeichenbereich mit einem Rechteck.
 *
 * @param float $x1
 * @param float $y1
 * @param float $x2
 * @param float $y2
 * @return Zend_Pdf_Page
 */
public function clipRectangle($x1, $y1, $x2, $y2);
]]></programlisting>
        <programlisting role="php"><![CDATA[
/**
 * Durchschneide den aktuellen Zeichenbereich mit einem Polygon.
 *
 * @param array $x  - Array mit Floats (die X Koordinaten der Eckpunkte)
 * @param array $y  - Array mit Floats (die Y Koordinaten der Eckpunkte)
 * @param integer $fillMethod
 * @return Zend_Pdf_Page
 */
public function clipPolygon($x,
                            $y,
                            $fillMethod =
                                Zend_Pdf_Page::FILL_METHOD_NON_ZERO_WINDING);
]]></programlisting>
        <programlisting role="php"><![CDATA[
/**
 * Durchschneide den aktuellen Zeichenbereich mit einem Kreis.
 *
 * @param float $x
 * @param float $y
 * @param float $radius
 * @param float $startAngle
 * @param float $endAngle
 * @return Zend_Pdf_Page
 */
public function clipCircle($x,
                           $y,
                           $radius,
                           $startAngle = null,
                           $endAngle = null);
]]></programlisting>
        <programlisting role="php"><![CDATA[
/**
 * Durchschneide den aktuellen Zeichenbereich mit einer Ellipse.
 *
 * Methoden Signaturen:
 * drawEllipse($x1, $y1, $x2, $y2);
 * drawEllipse($x1, $y1, $x2, $y2, $startAngle, $endAngle);
 *
 * @todo verarbeite die Sonderfälle mit $x2-$x1 == 0 oder $y2-$y1 == 0
 *
 * @param float $x1
 * @param float $y1
 * @param float $x2
 * @param float $y2
 * @param float $startAngle
 * @param float $endAngle
 * @return Zend_Pdf_Page
 */
public function clipEllipse($x1,
                            $y1,
                            $x2,
                            $y2,
                            $startAngle = null,
                            $endAngle = null);
]]></programlisting>
    </sect2>

    <sect2 id="zend.pdf.drawing.styles">
        <title>Stile</title>
        <para>
            Die <classname>Zend_Pdf_Style</classname> Klasse stellt Stilfunktionalitäten bereit.
        </para>
        <para>
            Stile können verwendet werden, um mit einer Operation die Parameter für den
            Grafikzustand zu speichern und auf eine PDF Seite anzuwenden:
        </para>
        <programlisting role="php"><![CDATA[
/**
 * Lege den Stil für zukünftige Zeichenoperationen auf dieser Seite fest
 *
 * @param Zend_Pdf_Style $style
 * @return Zend_Pdf_Page
 */
public function setStyle(Zend_Pdf_Style $style);

/**
 * Gebe den Stil der Seite zurück.
 *
 * @return Zend_Pdf_Style|null
 */
public function getStyle();
]]></programlisting>

        <para>
            Die <classname>Zend_Pdf_Style</classname> Klasse stellt einen Satz von Methoden bereit, um
            verschiedene Parameter des Grafikstadiums zu setzen und zu holen:
        </para>
        <programlisting role="php"><![CDATA[
/**
 * Setze die Linienfarbe.
 *
 * @param Zend_Pdf_Color $color
 * @return Zend_Pdf_Page
 */
public function setLineColor(Zend_Pdf_Color $color);
]]></programlisting>
        <programlisting role="php"><![CDATA[
/**
 * Hole die Linienfarbe.
 *
 * @return Zend_Pdf_Color|null
 */
public function getLineColor();
]]></programlisting>
        <programlisting role="php"><![CDATA[
/**
 * Setze die Linienbreite.
 *
 * @param float $width
 * @return Zend_Pdf_Page
 */
public function setLineWidth($width);
]]></programlisting>
        <programlisting role="php"><![CDATA[
/**
 * Hole die Linienbreite.
 *
 * @return float
 */
public function getLineWidth();
]]></programlisting>
        <programlisting role="php"><![CDATA[
/**
 * Setze das Strichmuster
 *
 * @param array $pattern
 * @param float $phase
 * @return Zend_Pdf_Page
 */
public function setLineDashingPattern($pattern, $phase = 0);
]]></programlisting>
        <programlisting role="php"><![CDATA[
/**
 * Hole das Strichmuster
 *
 * @return array
 */
public function getLineDashingPattern();
]]></programlisting>
        <programlisting role="php"><![CDATA[
/**
 * Get line dashing phase
 *
 * @return float
 */
public function getLineDashingPhase();
]]></programlisting>
        <programlisting role="php"><![CDATA[
/**
 * Setze die Füllfarbe
 *
 * @param Zend_Pdf_Color $color
 * @return Zend_Pdf_Page
 */
public function setFillColor(Zend_Pdf_Color $color);
]]></programlisting>
        <programlisting role="php"><![CDATA[
/**
 * Hole die Füllfarbe.
 *
 * @return Zend_Pdf_Color|null
 */
public function getFillColor();
]]></programlisting>
        <programlisting role="php"><![CDATA[
/**
 * Ändere den Zeichensatz.
 *
 * @param Zend_Pdf_Resource_Font $font
 * @param float $fontSize
 * @return Zend_Pdf_Page
 */
public function setFont(Zend_Pdf_Resource_Font $font, $fontSize);
]]></programlisting>
        <programlisting role="php"><![CDATA[
/**
 * Ändere die Schriftgröße
 *
 * @param float $fontSize
 * @return Zend_Pdf_Page
 */
public function setFontSize($fontSize);
]]></programlisting>
        <programlisting role="php"><![CDATA[
/**
 * Hole den Zeichensatz.
 *
 * @return Zend_Pdf_Resource_Font $font
 */
public function getFont();
]]></programlisting>
        <programlisting role="php"><![CDATA[
/**
 * Hole die Schriftgröße
 *
 * @return float $fontSize
 */
public function getFontSize();
]]></programlisting>
    </sect2>

    <sect2 id="zend.pdf.drawing.alpha">

        <title>Transparenz</title>

        <para>
            Das <classname>Zend_Pdf</classname> Modul unterstützt die Handhabung von Transparenz.
        </para>

        <para>
            Transparenz kann durch Verwendung der <classname>Zend_Pdf_Page::setAlpha()</classname> Methode gesetzt werden:

            <programlisting role="php"><![CDATA[

/**
 * Setzt die Transparenz
 *
 * $alpha == 0  - Transparent
 * $alpha == 1  - Opaque
 *
 * Von PDF unterstützte Transparent-Modi:
 * Normal (standard), Multiply, Screen, Overlay, Darken, Lighten,
 * ColorDodge, ColorBurn, HardLight, SoftLight, Difference, Exclusion
 *
 * @param float $alpha
 * @param string $mode
 * @throws Zend_Pdf_Exception
 * @return Zend_Pdf_Page
 */
public function setAlpha($alpha, $mode = 'Normal');
]]></programlisting>
        </para>
    </sect2>

</sect1>