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

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

    <sect2 id="zend.pdf.drawing.geometry">
        <title>Géométrie</title>

        <para>
            Le format <acronym>PDF</acronym> utilise la même géométrie que le format PostScript. Elle démarre
            d'en bas à gauche et est mesuré en points (1/72 inch soit 0,352778 mm).
        </para>

        <para>La taille d'une page peut-être récupéré depuis un objet page :</para>

        <para>
            <programlisting language="php"><![CDATA[
$width  = $pdfPage->getWidth();
$height = $pdfPage->getHeight();
]]></programlisting></para>
        </sect2>

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

        <para>
            Le format <acronym>PDF</acronym> a d'excellentes capacités dans la représentation des couleurs. Le
            module <classname>Zend_Pdf</classname> supporte les espaces de couleur : niveaux de
            gris, RGB et CMJN. Chacun d'entre eux peut-être utilisé à chaque fois qu'un objet
            <classname>Zend_Pdf_Color</classname> est requis. Les classes
            <classname>Zend_Pdf_Color_GrayScale</classname>,
            <classname>Zend_Pdf_Color_RGB</classname> et <classname>Zend_Pdf_Color_CMYK</classname>
            fournissent cette fonctionnalité :
        </para>

        <programlisting language="php"><![CDATA[
// $grayLevel (float). 0.0 (noir) - 1.0 (blanc)
$color1 = new Zend_Pdf_Color_GrayScale($grayLevel);

// $r, $g, $b (float).
// 0.0 (intensité mimimum) - 1.0 (intensité maximum)
$color2 = new Zend_Pdf_Color_RGB($r, $g, $b);

// $c, $m, $y, $k (float).
// 0.0 (intensité mimimum) - 1.0 (intensité maximum)
$color3 = new Zend_Pdf_Color_CMYK($c, $m, $y, $k);
]]></programlisting>

        <para>
            Les différentes couleurs HTML sont aussi fourni avec la classe
            <classname>Zend_Pdf_Color_Html</classname> :
        </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>Dessiner des formes</title>

        <para>
            Toutes les opérations de dessins peuvent être réalisées dans le contexte d'une
            page <acronym>PDF</acronym>.
        </para>

        <para>
            La classe <classname>Zend_Pdf_Page</classname> fournit les outils de dessins
            :
        </para>

        <para>
            <programlisting language="php"><![CDATA[
/**
 * Dessine une ligne de x1,y1 à 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></para>

        <para>
            <programlisting language="php"><![CDATA[
/**
 * Dessine un rectangle.
 *
 * Type de remplissage:
 * Zend_Pdf_Page::SHAPE_DRAW_FILL_AND_STROKE
 * - remplit le rectangle et dessine le contour (par défaut)
 * Zend_Pdf_Page::SHAPE_DRAW_STROKE
 * - trace uniquement le contour du rectangle
 * Zend_Pdf_Page::SHAPE_DRAW_FILL
 * - remplit le rectangle
 *
 * @param float $x1
 * @param float $y1
 * @param float $x2
 * @param float $y2
 * @return Zend_Pdf_Page
 * @param integer $fillType
 * @return Zend_Pdf_Page
 */
public function drawRectangle(
    $x1, $y1, $x2, $y2, $fillType = Zend_Pdf_Page::SHAPE_DRAW_FILL_AND_STROKE);
]]></programlisting></para>

        <para>
            <programlisting language="php"><![CDATA[
/**
 * Dessine un polygone.
 *
 * Si $fillType est Zend_Pdf_Page::SHAPE_DRAW_FILL_AND_STROKE
 * ou Zend_Pdf_Page::SHAPE_DRAW_FILL,
 * le polygone est automatiquement fermé.
 * Regardez la description détaillée de ces méthodes dans la
 * documentation du format PDF
 * (section 4.4.2 Path painting Operators, Filling)
 *
 * @param array $x  - tableau de float (les coordonnés X des sommets)
 * @param array $y  - tableau de float (les coordonnés Y des sommets)
 * @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></para>

        <para>
            <programlisting language="php"><![CDATA[
/**
 * Dessine un cercle avec comme centre  x, y et comme rayon radius.
 *
 * Les angles sont en radian
 *
 * Signatures des méthodes:
 * drawCircle($x, $y, $radius);
 * drawCircle($x, $y, $radius, $fillType);
 * drawCircle($x, $y, $radius, $startAngle, $endAngle);
 * drawCircle($x, $y, $radius, $startAngle, $endAngle, $fillType);
 *
 *
 * Ce n'est pas réellement un cercle, car le format supporte
 * uniquement des courbe de Bezier cubique.
 * Mais c'est une très bonne approximation.
 * La différence avec un vrai cercle est de au maximum 0.00026 radians
 * (avec les angles PI/8, 3*PI/8, 5*PI/8, 7*PI/8, 9*PI/8, 11*PI/8,
 * 13*PI/8 et 15*PI/8).
 * Avec les angles 0, PI/4, PI/2, 3*PI/4, PI, 5*PI/4, 3*PI/2 et 7*PI/4
 * c'est exactement la tangente d'un cercle.
 *
 * @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></para>

        <para>
            <programlisting language="php"><![CDATA[
/**
 * Dessine une ellipse dans le rectangle spécifié.
 *
 * Signatures des méthodes:
 * 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);
 *
 * Les angles sont en radians
 *
 * @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></para>
        </sect2>

        <sect2 id="zend.pdf.drawing.text-drawing">
            <title>Dessiner du texte</title>

        <para>
            Les opérations de dessins existent bien sûr dans le contexte d'une page <acronym>PDF</acronym>. Vous
            pouvez dessiner une seule ligne de texte à n'importe quelle endroit dans la page en
            fournissant les coordonnées x et y de la ligne de base. La police courant ainsi que sa
            taille seront utilisées pour le dessin (voir la description ci-dessous).
        </para>

        <para>
            <programlisting language="php"><![CDATA[
/**
 * Dessine une ligne de texte à la position x,y.
 *
 * @param string $text
 * @param float $x
 * @param float $y
 * @param string $charEncoding (optionnel) encodage des caractères du texte.
 * Par défaut le réglage système est utilisé.
 * @throws Zend_Pdf_Exception
 * @return Zend_Pdf_Page
 */
public function drawText($text, $x, $y, $charEncoding = '');
]]></programlisting></para>

            <example id="zend.pdf.drawing.text-drawing.example-1">
                <title>Dessiner une ligne dans la page</title>

                <programlisting language="php"><![CDATA[
...
$pdfPage->drawText('Bonjour le monde!', 72, 720);
...
]]></programlisting>
            </example>

        <para>
            Par défaut, les chaînes de texte sont interprétées en utilisant l'encodage du
            système. Si vous avez une chaîne qui utilise un encodage différent (comme les chaînes
            UTF-8 lues depuis une fichier sur le disque, ou une chaîne MacRoman obtenue depuis une
            base de données), vous pouvez indiquer l'encodage au moment du dessin et Zend_Pdf gérera
            la conversion pour vous. Vous pouvez fournir des chaînes dans n'importe quel encodage
            supporté par la fonction <code><ulink
            url="http://www.php.net/manual/function.iconv.php">iconv()</ulink></code> de <acronym>PHP</acronym>:
        </para>

        <example id="zend.pdf.drawing.text-drawing.example-2">
            <title>Dessiner une chaîne UTF-8 sur une page</title>

            <programlisting language="php"><![CDATA[
...
// Lit une chaîne UTF-8 à partir du disque
$unicodeString = fread($fp, 1024);

// Dessine une chaîne dans la page
$pdfPage->drawText($unicodeString, 72, 720, 'UTF-8');
...
]]></programlisting>
        </example>
    </sect2>

    <sect2 id="zend.pdf.drawing.using-fonts">
        <title>Utiliser des polices de caractères</title>

        <para>
            <methodname>Zend_Pdf_Page::drawText()</methodname> utilise la police courante ainsi
            que sa taille, qui sont définies avec la méthode
            <methodname>Zend_Pdf_Page::setFont()</methodname> :
        </para>

        <para>
            <programlisting language="php"><![CDATA[
/**
 * Choisit la police courante.
 *
 * @param Zend_Pdf_Resource_Font $font
 * @param float $fontSize
 * @return Zend_Pdf_Page
 */
public function setFont(Zend_Pdf_Resource_Font $font, $fontSize);
]]></programlisting></para>

        <para>
            Les documents <acronym>PDF</acronym> supportent PostScript Type 1 et les polices TrueType, mais
            également deux types spécifiques <acronym>PDF</acronym>, Type3 et les polices composites. Il y a aussi 14
            polices Type 1 standard intégré dans tout lecteur de <acronym>PDF</acronym> : Courier (4 styles), Helvetica
            (4 styles), Times (4 styles), Symbol, et Zapf Dingbats.
        </para>

        <para>
            Zend_Pdf supporte actuellement les 14 polices standard mais également vos propres
            police TrueType. Les objets de police obtenus via une des deux fabriques méthodes :
            <methodname>Zend_Pdf_Font::fontWithName($fontName)</methodname> pour les 14 polices <acronym>PDF</acronym>
            standard ou <methodname>Zend_Pdf_Font::fontWithPath($filePath)</methodname> pour les
            polices personnalisées.
        </para>

        <example id="zend.pdf.drawing.using-fonts.example-1">
            <title>Créer une police standard</title>

            <programlisting language="php"><![CDATA[
...
// Crée une nouvelle police
$font = Zend_Pdf_Font::fontWithName(Zend_Pdf_Font::FONT_HELVETICA);

// Applique la police
$pdfPage->setFont($font, 36);
...
]]></programlisting>
        </example>

        <para>
            Les constantes pour les 14 polices standard sont définis dans la classe
            <classname>Zend_Pdf_Font</classname> : <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_BOLD_ITALIC</para>
                    </listitem>

                    <listitem>
                        <para>Zend_Pdf_Font::FONT_TIMES</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_BOLD_ITALIC</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_BOLD_ITALIC</para>
                    </listitem>

                    <listitem>
                        <para>Zend_Pdf_Font::FONT_SYMBOL</para>
                    </listitem>

                    <listitem>
                        <para>Zend_Pdf_Font::FONT_ZAPFDINGBATS</para>
                    </listitem>
                </itemizedlist>
            </para>

        <para>
            Vous pouvez aussi prendre n'importe quelle police TrueType (extension habituelle
            ".ttf") ou OpenType (".otf") si elles ont une silhouette TrueType. Pour l'instant non
            supportée, les polices Mac Os X ".dfont" et les collections TrueType Microsoft (".ttc")
            seront intégrées dans une version future.
        </para>

        <para>
            Pour utiliser une police TrueType, vous devez fournir le chemin de fichier complet
            vers cette police. Si la police ne peut pas être lue pour une quelconque raison, ou si
            ce n'est pas une police TrueType, la méthode lèvera une exception :
        </para>

        <example id="zend.pdf.drawing.using-fonts.example-2">
            <title>Créer une police TrueType</title>

            <programlisting language="php"><![CDATA[
...
// Crée la nouvelle police
$goodDogCoolFont = Zend_Pdf_Font::fontWithPath('/chemin/vers/GOODDC__.TTF');

// Applique cette police
$pdfPage->setFont($goodDogCoolFont, 36);
...
]]></programlisting>
        </example>

        <para>
            Par défaut, les polices personnalisées seront incorporées dans le document <acronym>PDF</acronym>
            résultant. Cela permet aux destinataires de voir la page comme prévu, même s'ils ne font
            pas installer les polices appropriées sur leur système. En cas de problème avec la
            taille du fichier généré, vous pouvez demander que la police ne soit pas incorporé en
            passant l'option 'ne pas inclure' à la méthode de création :
        </para>

        <example id="zend.pdf.drawing.using-fonts.example-3">
            <title>Créer une police TrueType sans l'incorporer dans le document PDF</title>

            <programlisting language="php"><![CDATA[
...
// Crée la nouvelle police
$goodDogCoolFont =
    Zend_Pdf_Font::fontWithPath('/chemin/vers/GOODDC__.TTF',
                                Zend_Pdf_Font::EMBED_DONT_EMBED);

// Applique cette police
$pdfPage->setFont($goodDogCoolFont, 36);
...
]]></programlisting>
        </example>

        <para>
            Si les polices ne sont pas incorporées mais que le destinataire du fichier <acronym>PDF</acronym> a
            ces polices installées sur son système, il verra le document comme prévu. Si la police
            correcte n'est pas installée, l'application de visualisation du <acronym>PDF</acronym> fera de son mieux
            pour synthétiser une police de remplacement.
        </para>

        <para>
            Quelques polices ont les règles de licence très spécifiques qui les empêchent
            d'être incorporées dans des documents <acronym>PDF</acronym>. Donc vous devez faire attention, si vous
            essayez d'utiliser une police qui ne peut pas être incorporée, la méthode de création
            lèvera une exception.
        </para>

        <para>
            Vous pouvez toujours utiliser ces polices, mais vous devez passer le paramètre 'ne
            pas inclure' comme décrit ci-dessous, ou vous pouvez simplement bloquer l'exception
            :
        </para>

        <example id="zend.pdf.drawing.using-fonts.example-4">
            <title>Ne pas lever d'exception pour les polices ne pouvant être incorporées</title>

            <programlisting language="php"><![CDATA[
...
$font =
    Zend_Pdf_Font::fontWithPath('/chemin/vers/PoliceNonIncorporable.ttf',
                                Zend_Pdf_Font::EMBED_SUPPRESS_EMBED_EXCEPTION);
...
]]></programlisting>
        </example>

        <para>
            Cette technique de suppression est préférée si vous permettez aux utilisateurs de
            choisir leurs propres polices. Les polices qui peuvent être incorporées dans le document
            <acronym>PDF</acronym> le seront ; les autres ne le seront pas.
        </para>

        <para>
            Les fichiers de police peuvent être assez grands, certains peuvent atteindre des
            dizaines de méga-octets. Par défaut, toutes les polices incorporées sont comprimées en
            utilisant le schéma de compression Flate, ayant pour résultat un gain d'espace de 50% en
            moyenne. Si, pour une quelconque raison, vous ne voulez pas comprimer la police, vous
            pouvez le neutraliser avec une option :
        </para>

        <example id="zend.pdf.drawing.using-fonts.example-5">
            <title>Ne pas compresser une police incorporée</title>

            <programlisting language="php"><![CDATA[
...
$font =
    Zend_Pdf_Font::fontWithPath('/chemin/vers/PoliceDeGrandeTaille.ttf',
                                Zend_Pdf_Font::EMBED_DONT_COMPRESS);
...
]]></programlisting>
        </example>

        <para>
            En conclusion, si nécessaire, vous pouvez combiner les options d'incorporation en
            employant l'opérateur binaire OR :
        </para>

        <example id="zend.pdf.drawing.using-fonts.example-6">
            <title>Combiner les options de polices incorporées</title>

            <programlisting language="php"><![CDATA[
...
$font = Zend_Pdf_Font::fontWithPath(
    $cheminVersPoliceQuelconque,
    (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>Limitations des polices standard PDF</title>

        <para>
            Les polices standard <acronym>PDF</acronym> emploient en interne plusieurs encodages sur un seul
            octet (voir <ulink
            url="http://www.adobe.com/devnet/acrobat/pdfs/pdf_reference_1-7.pdf">PDF Reference,
            Sixth Edition, version 1.7</ulink> - Annexe D pour plus de détails). Elles sont
            généralement avec un jeu de caractère de type Latin1(excepté les polices Symbol and
            ZapfDingbats).
        </para>

        <para>
            <classname>Zend_Pdf</classname> utilise l'encodage CP1252 (WinLatin1) pour tracer
            les textes avec les polices standard.
        </para>

        <para>
            Le texte peut encore être fourni dans n'importe quel autre encodage, qui doit être
            spécifié s'il diffère de celui en cours. Seulement les caractères WinLatin1 seront
            tracés réellement.
        </para>

        <example id="zend.pdf.drawing.using-fonts.example-7">
            <title>Combiner les options de polices embarqués</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>Extraction des polices</title>

        <para>
            Depuis la version 1.5, <classname>Zend_Pdf</classname> fournit la possibilité
            d'extraire les polices des documents chargés.
        </para>

        <para>
            Ceci peut être utile lors des mises à jour de document avec ajout de texte. Sans
            cette fonctionnalité vous devez attacher et probablement intégrer la police dans le
            document chaque fois que vous voulez le mettre à jour.
        </para>

        <para>
            Les objets <classname>Zend_Pdf</classname> et <classname>Zend_Pdf_Page</classname>
            fournissent une méthode spéciale pour extraire toutes les polices mentionnés à
            l'intérieur d'un document ou d'une page :
        </para>

        <example id="zend.pdf.drawing.extracting-fonts.example-1">
            <title>Extraction de polices à partir d'un document chargé</title>

            <programlisting language="php"><![CDATA[
...
$pdf = Zend_Pdf::load($cheminVersDocument);
...
// Récupère toutes les polices du document
$listePolice = $pdf->extractFonts();
$pdf->pages[] = ($page = $pdf->newPage(Zend_Pdf_Page::SIZE_A4));
$yPosition = 700;
foreach ($listePolice as $police) {
    $page->setFont($police, 15);
    $page->drawText(
        $police->getFontName(Zend_Pdf_Font::NAME_POSTSCRIPT, 'fr', 'UTF-8')
      . ': Le renard brun rapide saute par-dessus le chien paresseux',
        100,
        $yPosition,
        'UTF-8');
    $yPosition -= 30;
}
...
// Récupère toutes les polices référencées dans la première page du document
$firstPage = reset($pdf->pages);
$firstPageFonts = $firstPage->extractFonts();
...
]]></programlisting>
        </example>

        <example id="zend.pdf.drawing.extracting-fonts.example-2">
            <title>Extraction d'une police à partir d'un document chargé en spécifiant le nom de
            police</title>

            <programlisting language="php"><![CDATA[
...
$pdf = new Zend_Pdf();
...
$pdf->pages[] = ($page = $pdf->newPage(Zend_Pdf_Page::SIZE_A4));

$police = Zend_Pdf_Font::fontWithPath($cheminVersPolices);
$page->setFont($police, $taillePolice);
$page->drawText($texte, $x, $y);
...
// Ce nom de police peut être stocké quelquepart...
$fontName = $font->getFontName(Zend_Pdf_Font::NAME_POSTSCRIPT, 'fr', 'UTF-8');
...
$pdf->save($cheminVersDocument);
...
]]></programlisting>

            <programlisting language="php"><![CDATA[
...
$pdf = Zend_Pdf::load($cheminVersDocument);
...
$pdf->pages[] = ($page = $pdf->newPage(Zend_Pdf_Page::SIZE_A4));

$police = $pdf->extractFont($nomPolice);
/* $pageSource->extractFont($nomPolice) peut aussi être utilisé ici */
$page->setFont($police, $taillePolice);
$page->drawText($texte, $x, $y);
...
$pdf->save($cheminVersDocument, true /* mise à jour de type incrémental */);
...
]]></programlisting>
        </example>

        <para>
            Les polices extraites peuvent être utilisées à la place de n'importe quelle autre
            police avec les limitations suivantes : <itemizedlist>
                    <listitem>
                    <para>
                        La police extraite peut être employée seulement dans le cadre du
                        document à partir duquel elle a été extraite.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        Les possibles programmes de polices incorporées ne sont pas extraits
                        réellement. La police ainsi extraite ne peut pas fournir la métrique
                        correcte de police et la police originale doit être utilisée pour les
                        calculs de largeur des textes : <programlisting language="php"><![CDATA[
...
$police = $pdf->extractFont($fontName);
$policeOriginal = Zend_Pdf_Font::fontWithPath($cheminVersPolices);

/* utilisation d'une police extraite */
$page->setFont($police, $taillePolice);
$xPosition = $x;
for ($charIndex = 0; $charIndex < strlen($text); $charIndex++) {
    $page->drawText($text[$charIndex], $xPosition, $y);

    // Use original font for text width calculation
    $width = $originalFont->widthForGlyph(
                $originalFont->glyphNumberForCharacter($text[$charIndex])
             );
    $xPosition += $width / $originalFont->getUnitsPerEm() * $taillePolice;
}
...
]]></programlisting></para>
                    </listitem>
                </itemizedlist>
            </para>
    </sect2>

    <sect2 id="zend.pdf.drawing.image-drawing">
        <title>Insertion d'images</title>

        <para>
            La classe <classname>Zend_Pdf_Page</classname> fournis la méthode
            <methodname>drawImage()</methodname> pour dessiner une image :
        </para>

        <para>
            <programlisting language="php"><![CDATA[
/**
 * Insère une image à la position spécifiée dans la page
 *
 * @param Zend_Pdf_Resource_Image $image
 * @param float $x1
 * @param float $y1
 * @param float $x2
 * @param float $y2
 * @return Zend_Pdf_Page
 */
public function drawImage(Zend_Pdf_Resource_Image $image, $x1, $y1, $x2, $y2);
]]></programlisting></para>

        <para>
            Les objets Image peuvent être créés avec la méthode
            <methodname>Zend_Pdf_Image::imageWithPath($filePath)</methodname> (les images JPG, PNG et
            TIFF sont maintenant supportées) :
        </para>

        <example id="zend.pdf.drawing.image-drawing.example-1">
            <title>Insertion d'images</title>

            <programlisting language="php"><![CDATA[
...
//Charger une image
$image = Zend_Pdf_Image::imageWithPath('mon_image.jpg');

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

        <para>
            <emphasis>Important ! Le support JPEG nécessite que l'extension <acronym>PHP</acronym> GD soit
            installé.</emphasis> <emphasis>Important ! Le support PNG nécessite que l'extension ZLIB
            soit configuré pour accepter les images avec canaux Alpha.</emphasis>
        </para>

        <para>
            Lisez la documentation de <acronym>PHP</acronym> pour plus d'informations (<ulink
            url="http://www.php.net/manual/fr/ref.image.php">http://www.php.net/manual/fr/ref.image.php</ulink>
            et <ulink
            url="http://www.php.net/manual/fr/ref.zlib.php">http://www.php.net/manual/fr/ref.zlib.php</ulink>).
        </para>
    </sect2>

    <sect2 id="zend.pdf.drawing.line-drawing-style">
        <title>Style de lignes</title>

        <para>
            Le style de ligne est définit par l'épaisseur, la couleur et le style de tiret.
            Tout ces paramètres peuvent être assignés par les méthodes de la classe
            <classname>Zend_Pdf_Page</classname> :
        </para>

        <para>
            <programlisting language="php"><![CDATA[
/** Choisit la couleur de ligne. */
public function setLineColor(Zend_Pdf_Color $color);

/** Choisit l'épaisseur de ligne. */
public function setLineWidth(float $width);

/**
 * Choisit le modèle de tiret.
 *
 * modele est un tableau de floats: array(longueur_visible,
 * longueur_invisible, longueur_visible, longueur_invisible,
 * ...)
 * phase est le décalage à partir du début de la ligne.
 *
 * @param array $modele
 * @param array $phase
 * @return Zend_Pdf_Page
 */
public function setLineDashingPattern($pattern, $phase = 0);
]]></programlisting></para>
        </sect2>

        <sect2 id="zend.pdf.drawing.fill-style">
            <title>Style de remplissage</title>

        <para>
            Les méthodes <methodname>Zend_Pdf_Page::drawRectangle()</methodname>,
            <methodname>Zend_Pdf_Page::drawPoligon()</methodname>,
            <methodname>Zend_Pdf_Page::drawCircle()</methodname> et
            <methodname>Zend_Pdf_Page::drawEllipse()</methodname> prennent en argument optionnel le
            type de remplissage: <varname>$fillType</varname>. Il peut être :
        </para>

        <itemizedlist>
            <listitem>
                <para>Zend_Pdf_Page::SHAPE_DRAW_STROKE - trace le contour de la forme</para>
            </listitem>

            <listitem>
                <para>Zend_Pdf_Page::SHAPE_DRAW_FILL - remplit uniquement la forme</para>
            </listitem>

            <listitem>
                <para>
                    Zend_Pdf_Page::SHAPE_DRAW_FILL_AND_STROKE - remplissage et contour (par
                    défaut)
                </para>
            </listitem>
        </itemizedlist>

        <para>
            La méthode <methodname>Zend_Pdf_Page::drawPoligon()</methodname> prend aussi
            paramètre supplémentaire <varname>$fillMethod</varname> :
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    $fillMethod = Zend_Pdf_Page::FILL_METHOD_NON_ZERO_WINDING (par
                    défaut)
                </para>

                <para>
                    La <citetitle>référence du format <acronym>PDF</acronym></citetitle> décrit la règle comme
                    ceci : <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 <acronym>PDF</acronym> 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>
                    La <citetitle>référence du format <acronym>PDF</acronym></citetitle> décrit la règle comme
                    ceci : <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 <acronym>PDF</acronym> 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>Transformations linéaires</title>

        <sect3 id="zend.pdf.drawing.linear-transformations.rotations">
            <title>Rotations</title>

            <para>
                La page <acronym>PDF</acronym> page peut être tourné avant d'appliquer toute opération de dessin.
                Ceci peut être fait avec la méthode <methodname>Zend_Pdf_Page::rotate()</methodname>
                :
            </para>

            <programlisting language="php"><![CDATA[
/**
 * Rotation de la page
 *
 * @param float $x  - la coordonnée X du point de rotation
 * @param float $y  - la coordonnée X du point de rotation
 * @param float $angle - angle de rotation
 * @return Zend_Pdf_Page
 */
public function rotate($x, $y, $angle);
]]></programlisting>
        </sect3>

        <sect3 id="zend.pdf.drawing.linear-transformations.scale">
            <title>A partir de Zend Framework 1.8, mise à l'échelle</title>

            <para>
                La mise à l'échelle est fournie par la méthode
                <methodname>Zend_Pdf_Page::scale()</methodname> :
            </para>

            <programlisting language="php"><![CDATA[
/**
 * Mise à l'échelle
 *
 * @param float $xScale - X dimention scale factor
 * @param float $yScale - Y dimention scale factor
 * @return Zend_Pdf_Page
 */
public function scale($xScale, $yScale);
]]></programlisting>
        </sect3>

        <sect3 id="zend.pdf.drawing.linear-transformations.translate">
            <title>A partir de Zend Framework 1.8, décalage</title>

            <para>
                Le décalage du système de coordonnées est réalisé par la méthode
                <methodname>Zend_Pdf_Page::translate()</methodname> :
            </para>

            <programlisting language="php"><![CDATA[
/**
 * Décalage du système de coordonnées
 *
 * @param float $xShift - coordonnées X du décalage
 * @param float $yShift - coordonnées Y du décalage
 * @return Zend_Pdf_Page
 */
public function translate($xShift, $yShift);
]]></programlisting>
        </sect3>

        <sect3 id="zend.pdf.drawing.linear-transformations.skew">
            <title>A partir de Zend Framework 1.8, mise en biais</title>

            <para>
                La mise en biais de la page peut être réalisé par la méthode
                <methodname>Zend_Pdf_Page::skew()</methodname> :
            </para>

            <programlisting language="php"><![CDATA[
/**
 * Mise en biais du système de coordonnées
 *
 * @param float $x  - the X co-ordinate of axis skew point
 * @param float $y  - the Y co-ordinate of axis skew point
 * @param float $xAngle - X axis skew angle
 * @param float $yAngle - Y axis skew angle
 * @return Zend_Pdf_Page
 */
public function skew($x, $y, $xAngle, $yAngle);
]]></programlisting>
        </sect3>
    </sect2>

    <sect2 id="zend.pdf.drawing.save-restore">
        <title>Sauvegarder et restaurer l'état graphique</title>

        <para>
            L'état graphique (police courante, taille de caractère, couleur de ligne, couleur
            de remplissage, style de ligne, sens de la page, zone de dessin) peut-être sauvegarder à
            tout moment. L'opération de sauvegarde empile le contexte dans une pile de contexte
            graphique, l'opération de restauration récupère le contexte depuis la pile.
        </para>

        <para>
            Il y a deux méthodes dans la classe <classname>Zend_Pdf_Page</classname> pour
            réaliser ces opérations :
        </para>

        <para>
            <programlisting language="php"><![CDATA[
/**
 * Sauvegarde l'état graphique de la page.
 * Cela prend un instantané des styles courants, des zones de dessins
 * et de toutes les rotations/translations/changements de taille appliqués.
 *
 * @return Zend_Pdf_Page
 */
public function saveGS();

/**
 * Restaure le dernier état graphique sauvegarder avec saveGS().
 *
 * @return Zend_Pdf_Page
 */
public function restoreGS();
]]></programlisting></para>
        </sect2>

        <sect2 id="zend.pdf.drawing.clipping">
            <title>Zone de dessin</title>

        <para>
            Le format <acronym>PDF</acronym> et le module Zend_Pdf supporte le découpage de la zone de dessin. La
            zone de dessin courante limite la zone de la page affectée par l'utilisation des
            opérateurs de dessins. Initialement c'est toute la page.
        </para>

        <para>
            La classe <classname>Zend_Pdf_Page</classname> fournit des méthodes pour les
            opérations de découpage.
        </para>

        <para>
            <programlisting language="php"><![CDATA[
/**
 * Découpe la zone courante avec un rectangle.
 *
 * @param float $x1
 * @param float $y1
 * @param float $x2
 * @param float $y2
 * @return Zend_Pdf_Page
 */
public function clipRectangle($x1, $y1, $x2, $y2);
]]></programlisting></para>

        <para>
            <programlisting language="php"><![CDATA[
/**
 * Découpe la zone courante avec un polygone.
 *
 * @param array $x  - tableau de float (les coordonnées X des sommets)
 * @param array $y  - tableau de float (les coordonnées Y des sommets)
 * @param integer $fillMethod
 * @return Zend_Pdf_Page
 */
public function clipPolygon(
    $x, $y, $fillMethod = Zend_Pdf_Page::FILL_METHOD_NON_ZERO_WINDING);
]]></programlisting></para>

        <para>
            <programlisting language="php"><![CDATA[
/**
 * Découpe la zone courante avec un cercle.
 *
 * @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></para>

        <para>
            <programlisting language="php"><![CDATA[
/**
 * Découpe la zone courante avec une ellipse.
 *
 * Signatures des méthodes:
 * drawEllipse($x1, $y1, $x2, $y2);
 * drawEllipse($x1, $y1, $x2, $y2, $startAngle, $endAngle);
 *
 * @todo s'occuper des cas spéciaux avec $x2-$x1 == 0 ou $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></para>
        </sect2>

        <sect2 id="zend.pdf.drawing.styles">
            <title>Styles</title>

        <para>
            La classe <classname>Zend_Pdf_Style</classname> fournit les fonctionnalités de
            style.
        </para>

        <para>
            Les styles peuvent être utilisés pour stocker des paramètre d'état graphique et de
            les appliquer à une page <acronym>PDF</acronym> en une seule opération :
        </para>

        <para>
            <programlisting language="php"><![CDATA[
/**
 * Choisit le style à utiliser pour les futures opérations
 * de dessin sur cette page
 *
 * @param Zend_Pdf_Style $style
 * @return Zend_Pdf_Page
 */
public function setStyle(Zend_Pdf_Style $style);

/**
 * Renvoie le style appliqué à la page.
 *
 * @return Zend_Pdf_Style|null
 */
public function getStyle();
]]></programlisting></para>

        <para>
            La classe <classname>Zend_Pdf_Style</classname> fournit des méthodes pour choisir
            ou récupérer différents paramètres de l'état graphique :
        </para>

        <para>
            <programlisting language="php"><![CDATA[
/**
 * Choisit la couleur de ligne.
 *
 * @param Zend_Pdf_Color $color
 * @return Zend_Pdf_Page
 */
public function setLineColor(Zend_Pdf_Color $color);
]]></programlisting></para>

        <para>
            <programlisting language="php"><![CDATA[
/**
 * Récupère la couleur de ligne.
 *
 * @return Zend_Pdf_Color|null
 * @return Zend_Pdf_Page
 */
public function getLineColor();
]]></programlisting></para>

        <para>
            <programlisting language="php"><![CDATA[
/**
 * Choisit l'épaisseur de ligne.
 *
 * @param float $width
 * @return Zend_Pdf_Page
 */
public function setLineWidth($width);
]]></programlisting></para>

        <para>
            <programlisting language="php"><![CDATA[
/**
 * Récupère l'épaisseur de ligne.
 *
 * @return float
 * @return Zend_Pdf_Page
 */
public function getLineWidth($width);
]]></programlisting></para>

        <para>
            <programlisting language="php"><![CDATA[
/**
 * Choisit le style de tiret
 *
 * @param array $pattern
 * @param float $phase
 * @return Zend_Pdf_Page
 */
public function setLineDashingPattern($pattern, $phase = 0);
]]></programlisting></para>

        <para>
            <programlisting language="php"><![CDATA[
/**
 * Récupère le style de tiret
 *
 * @return array
 */
public function getLineDashingPattern();
]]></programlisting></para>

        <para>
            <programlisting language="php"><![CDATA[
/**
 * Récupère le modèle de tiret
 *
 * @return float
 */
public function getLineDashingPhase();
]]></programlisting></para>

        <para>
            <programlisting language="php"><![CDATA[
/**
 * Choisit la couleur de remplissage.
 *
 * @param Zend_Pdf_Color $color
 * @return Zend_Pdf_Page
 */
public function setFillColor(Zend_Pdf_Color $color);
]]></programlisting></para>

        <para>
            <programlisting language="php"><![CDATA[
/**
 * Récupère la couleur de remplissage.
 *
 * @return Zend_Pdf_Color|null
 */
public function getFillColor();
]]></programlisting></para>

        <para>
            <programlisting language="php"><![CDATA[
/**
 * Choisit la police.
 *
 * @param Zend_Pdf_Font $font
 * @param Zend_Pdf_Resource_Font $font
 * @param float $fontSize
 */
public function setFont(Zend_Pdf_Resource_Font $font, $fontSize);
]]></programlisting></para>

        <para>
            <programlisting language="php"><![CDATA[
/**
 * Modifie la taille de police.
 *
 * @param float $fontSize
 * @return Zend_Pdf_Page
 */
public function setFontSize($fontSize);
]]></programlisting></para>

        <para>
            <programlisting language="php"><![CDATA[
/**
 * Récupère la police courante
 *
 * @return Zend_Pdf_Resource_Font $font
 */
public function getFont();
]]></programlisting></para>

        <para>
            <programlisting language="php"><![CDATA[
/**
 * Récupère la taille de la police
 *
 * @return float $fontSize
 */
public function getFontSize();
]]></programlisting></para>
        </sect2>

        <sect2 id="zend.pdf.drawing.alpha">
            <title>Transparence</title>

        <para>
            Le module <classname>Zend_Pdf</classname> supporte la gestion de la
            transparence.
        </para>

        <para>
            La transparence peut être paramétré en utilisant la méthode
            <methodname>Zend_Pdf_Page::setAlpha()</methodname> : <programlisting language="php"><![CDATA[
/**
 * Règle la transparence
 *
 * $alpha == 0  - transparent
 * $alpha == 1  - opaque
 *
 * Transparency modes, supported by PDF:
 * Normal (default), 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>