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

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

    <sect2 id="zend.pdf.drawing.geometry">
        <title>Geometrie</title>

        <para>
            <acronym>PDF</acronym> 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 language="php"><![CDATA[
$width  = $pdfPage->getWidth();
$height = $pdfPage->getHeight();
]]></programlisting>
    </sect2>

    <sect2 id="zend.pdf.drawing.color">
        <title>Farben</title>

        <para>
            <acronym>PDF</acronym> 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 language="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>
            Die <acronym>HTML</acronym> Farben werden auch durch die Klasse
            <classname>Zend_Pdf_Color_Html</classname> bereitgestellt:
        </para>

        <programlisting language="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 <acronym>PDF</acronym> Seite
            durchgeführt werden.
        </para>

        <para>
            Die <classname>Zend_Pdf_Page</classname> Klass stellt einen Satz von einfachen Formen
            bereit:
        </para>

        <programlisting language="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 language="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 language="php"><![CDATA[
/**
 * Zeichne ein gerundetes 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
 *
 * radius ist ein Integer der den Radius der vier Ecken repräsentiert, oder ein
 * Arraay von vier Integern welche den Radius beginnend mit Links oben
 * repräsentieren, und im Uhrzeigersinn weitergehen
 *
 * @param float $x1
 * @param float $y1
 * @param float $x2
 * @param float $y2
 * @param integer|array $radius
 * @param integer $fillType
 * @return Zend_Pdf_Page
 */
public function drawRoundedRectangle($x1, $y1, $x2, $y2, $radius,
                       $fillType = Zend_Pdf_Page::SHAPE_DRAW_FILL_AND_STROKE);
]]></programlisting>

        <programlisting language="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 language="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 language="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 <acronym>PDF</acronym> 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 language="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 language="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
            <acronym>PHP</acronym>'s <ulink
                url="http://www.php.net/manual/function.iconv.php">iconv()</ulink> 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 language="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>
            <methodname>Zend_Pdf_Page::drawText()</methodname> verwendet den aktuellen Zeichensatz
            und die aktuelle Zeichengröße der Seite, die mit der Methode
            <methodname>Zend_Pdf_Page::setFont()</methodname> festgelegt werden:
        </para>

        <programlisting language="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>
            <acronym>PDF</acronym> Dokumente unterstützt PostScript Type1 und TrueType Zeichensätze,
            sowie die zwei speziellen <acronym>PDF</acronym> Typen Type3 und zusammengesetzte
            Zeichensätze (composite fonts). Es gibt zudem 14 Type1 Standardzeichensätze, die von
            jedem <acronym>PDF</acronym> 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
            <acronym>PDF</acronym> Standardzeichensätze sowie deine eigenen TrueType Zeichensätze.
            Zeichensatzobjekte können über eine der zwei Fabrikmethoden (factory methods) erhalten
            werden: <methodname>Zend_Pdf_Font::fontWithName($fontName)</methodname> für die 14
            <acronym>PDF</acronym> Standardzeichensätze oder
            <methodname>Zend_Pdf_Font::fontWithPath($filePath)</methodname> für eigene Zeichensätze.
        </para>

        <example id="zend.pdf.drawing.using-fonts.example-1">
            <title>Einen Standardzeichensatz erstellen</title>

            <programlisting language="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 <acronym>PDF</acronym> 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>Einen TrueType Zeichensatz erstellen</title>

            <programlisting language="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 <acronym>PDF</acronym>
            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 language="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
            <acronym>PDF</acronym> 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 <acronym>PDF</acronym> Viewer sich bemühen, um einen Ersatz
            herzustellen.
        </para>

        <para>
            Einige Zeichensätze haben sehr spezielle Lizensierungsregeln, die das Einbetten in
            <acronym>PDF</acronym> 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 language="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 <acronym>PDF</acronym>
            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 language="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 language="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 <acronym>PDF</acronym> 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 language="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 language="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 language="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 language="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:
                    </para>

                    <programlisting language="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>
                </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 language="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
            <methodname>Zend_Pdf_Image::imageWithPath($filePath)</methodname> 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 language="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
                <acronym>PHP</acronym> 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 <acronym>PHP</acronym> 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 language="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 <methodname>Zend_Pdf_Page::drawRectangle()</methodname>,
            <methodname>Zend_Pdf_Page::drawPolygon()</methodname>,
            <methodname>Zend_Pdf_Page::drawCircle()</methodname> und
            <methodname>Zend_Pdf_Page::drawEllipse()</methodname> akzeptieren das
            <varname>$fillType</varname> 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 <methodname>Zend_Pdf_Page::drawPolygon()</methodname> Methode akzeptiert
            <varname>$fillMethod</varname> 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>
                            Die Regel der nicht-Null Fensternummer erkennt ob ein gegebener Punkt in
                            einem Pfad liegt, indem konzeptuell ein Strahl von diesem Punkt in die
                            Unendlichkeit in jede Richtung gezeichnet wird und dann die Plätze
                            betrachtet werden an denen der Pfad den Strahl kreuzt. Beginnend mit der
                            Anzahl 0, fügt die Regel jedesmal 1 hinzu wenn ein Pfadsegment den
                            Strahl von links nach rechts kreuzt, und substrahiert jedesmal 1 wenn
                            ein Segment von rechts nach links kreuzt. Wenn nach dem Zählen aller
                            Kreuzungen das Ergebnis ß ist, dann ist der Punkt ausserhalb des Pfades;
                            andernfalls ist er innerhalb. Beachte: Die gerade beschriebene Methode
                            spezifiziert nicht was zu tun ist wenn ein Pfadsegment mit dem gewählten
                            Strahl übereinstimmt oder ihn tangiert. Da die Richtung des Strahls
                            beliebig ist wählt die Regel einen Strahl der solche problematischen
                            Schnittpunkte nicht verursacht. Für einfache konvexe Pfade, definierte
                            die Regel der nicht-Null Fensternummer das Innen und Aussen wie man es
                            intuitiv erwarten würde. Die interessanteren Fälle sind jene die
                            komplexe oder selbst-schneidenden Pfade wie jene in Figur 4.10 gezeigt
                            (in der <acronym>PDF</acronym> Referenz). Für einen Pfad der aus einem
                            fünf-punktigen Stern besteht, und mit fünf verbundenen geraden Linien
                            besteht die sich gegenseitig schneiden, nimmt die Regel an dass das
                            Innen die komplette Fläche ist, welche vom Stern eingeschlossen wird,
                            inklusive dem Pentagon in der Mitte. Für einen Pfad der aus zwei
                            konzentrischen Kreisen besteht, wird angenommen das die Fläche welche
                            von beiden Kreisen eingeschlossen wird innen ist, wobei beide in der
                            selben Richtung gezeichnet sein müssen. Wenn die Kreise in
                            entgegengesetzten Richtungen gezeichnet werden, wird nur die "Donut"
                            Form zwischen Ihnen als Innen angenommen, entsprechend der Regel; das
                            "Donut Loch" ist Aussen.
                        </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>
                            Eine alternative zur Regel der nicht-Null Fensternummer ist die
                            gerade-ungerade Regel. Diese Regel erkennt die "Innenhaftigkeit" eines
                            Punktes indem ein Strahl von diesem Punkt in jede Richtung gezeichnet
                            wird und einfach die Anzahl der Pfadsegmente gezählt wird, welche den
                            Strahl kreuzen, unabhängig von der Richtung. Wenn die Anzahl ungerade
                            ist, dann ist der Punkt innerhalb; ist Sie gerade ist der Punkt
                            ausserhalb. Das verursacht die gleichen Resultate wie die Regel der
                            nicht-Null Fensternummer für Pfade mit einfachen Formen, produziert aber
                            unterschiedliche Resultate für komplexere Formen. Figur 4.11 (in der
                            <acronym>PDF</acronym> Referenz) zeigt die Effekte wenn die
                            gerade-ungerade Regel auf komplexe Pfade angewendet wird. Für den
                            Fünf-punktigen Stern nimmt die Regel an dass die Triangularpunkte
                            innerhalb des Pfades liegen, aber nicht das Pentagon im Zentrum. Für die
                            zwei konzentrischen Kreise, wird nur von der "Donut" Form angenommen das
                            Sie innerhalb liegt, unabhängig von der Richtung in welcher die Kreise
                            gezeichnet werden.
                        </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 <acronym>PDF</acronym> Seiten
                gedreht werden. Dies kann mit Hilfe der
                <methodname>Zend_Pdf_Page::rotate()</methodname> Methode durchgeführt werden:
            </para>

            <programlisting language="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 <methodname>Zend_Pdf_Page::scale()</methodname>
                Methode angeboten:
            </para>

            <programlisting language="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
                <methodname>Zend_Pdf_Page::translate()</methodname> Methode durchgeführt:
            </para>

            <programlisting language="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
                <methodname>Zend_Pdf_Page::skew()</methodname> Methode durchgeführt werden:
            </para>

            <programlisting language="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 language="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>
            <acronym>PDF</acronym> 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 language="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 language="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 language="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 language="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 <acronym>PDF</acronym> Seite anzuwenden:
        </para>

        <programlisting language="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 language="php"><![CDATA[
/**
 * Setze die Linienfarbe.
 *
 * @param Zend_Pdf_Color $color
 * @return Zend_Pdf_Page
 */
public function setLineColor(Zend_Pdf_Color $color);
]]></programlisting>

        <programlisting language="php"><![CDATA[
/**
 * Hole die Linienfarbe.
 *
 * @return Zend_Pdf_Color|null
 */
public function getLineColor();
]]></programlisting>

        <programlisting language="php"><![CDATA[
/**
 * Setze die Linienbreite.
 *
 * @param float $width
 * @return Zend_Pdf_Page
 */
public function setLineWidth($width);
]]></programlisting>

        <programlisting language="php"><![CDATA[
/**
 * Hole die Linienbreite.
 *
 * @return float
 */
public function getLineWidth();
]]></programlisting>

        <programlisting language="php"><![CDATA[
/**
 * Setze das Strichmuster
 *
 * @param array $pattern
 * @param float $phase
 * @return Zend_Pdf_Page
 */
public function setLineDashingPattern($pattern, $phase = 0);
]]></programlisting>

        <programlisting language="php"><![CDATA[
/**
 * Hole das Strichmuster
 *
 * @return array
 */
public function getLineDashingPattern();
]]></programlisting>

        <programlisting language="php"><![CDATA[
/**
 * Get line dashing phase
 *
 * @return float
 */
public function getLineDashingPhase();
]]></programlisting>

        <programlisting language="php"><![CDATA[
/**
 * Setze die Füllfarbe
 *
 * @param Zend_Pdf_Color $color
 * @return Zend_Pdf_Page
 */
public function setFillColor(Zend_Pdf_Color $color);
]]></programlisting>

        <programlisting language="php"><![CDATA[
/**
 * Hole die Füllfarbe.
 *
 * @return Zend_Pdf_Color|null
 */
public function getFillColor();
]]></programlisting>

        <programlisting language="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 language="php"><![CDATA[
/**
 * Ändere die Schriftgröße
 *
 * @param float $fontSize
 * @return Zend_Pdf_Page
 */
public function setFontSize($fontSize);
]]></programlisting>

        <programlisting language="php"><![CDATA[
/**
 * Hole den Zeichensatz.
 *
 * @return Zend_Pdf_Resource_Font $font
 */
public function getFont();
]]></programlisting>

        <programlisting language="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 <methodname>Zend_Pdf_Page::setAlpha()</methodname>
            Methode gesetzt werden:
        </para>

        <programlisting language="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>
    </sect2>
</sect1>