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

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

    <sect2 id="zend.pdf.drawing.geometry">
        <title>Geometría</title>
        <para>
        PDF utiliza la misma geometría que PostScript. Se inicia desde la parte 
        inferior izquierda de la página y por defecto se mide en puntos (1/72 de 
        pulgada).
        </para>
        <para>
        El tamaño de la página se puede recuperar desde un objeto página:
        </para>
        <para>
            <programlisting role="php"><![CDATA[
$width  = $pdfPage->getWidth();
$height = $pdfPage->getHeight();
]]></programlisting>
        </para>
    </sect2>

    <sect2 id="zend.pdf.drawing.color">
        <title>Colores</title>
        <para>
        PDF tiene una poderosa capacidad de representación de colores. 
        El módulo <classname>Zend_Pdf</classname> soporta la Escala de Grises, 
        y los espacios de color RGB y CMYK. 
        Cualquiera de ellos puede ser usado en cualquier lugar, donde el objeto 
        <classname>Zend_Pdf_Color</classname> sea requerido. 
        Las clases <classname>Zend_Pdf_Color_GrayScale</classname>,
        <classname>Zend_Pdf_Color_Rgb</classname> y 
        <classname>Zend_Pdf_Color_Cmyk</classname> proporcionan esta funcionalidad:
        </para>
        <programlisting role="php"><![CDATA[
// $grayLevel (float number). 0.0 (black) - 1.0 (white)
$color1 = new Zend_Pdf_Color_GrayScale($grayLevel);

// $r, $g, $b (float numbers). 0.0 (min intensity) - 1.0 (max intensity)
$color2 = new Zend_Pdf_Color_Rgb($r, $g, $b);

// $c, $m, $y, $k (float numbers). 0.0 (min intensity) - 1.0 (max intensity)
$color3 = new Zend_Pdf_Color_Cmyk($c, $m, $y, $k);
]]></programlisting>

        <para>
            Los estilos de colores HTML también se proporcionan con la clase 
            <classname>Zend_Pdf_Color_Html</classname>:
        </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>Dibujo de Formas</title>
        <para>
            Todas las operaciones de dibujo se puede hacer en un contexto de página PDF.
        </para>
        <para>
            La clase <classname>Zend_Pdf_Page</classname> proporciona un conjunto de 
            primitivas de dibujo:
        </para>
        <programlisting role="php"><![CDATA[
/**
 * Dibujar una línea desde x1,y1 hasta 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[
/**
 * Dibujar un rectángulo.
 *
 * Rellenar los tipos:
 * Zend_Pdf_Page::SHAPE_DRAW_FILL_AND_STROKE - rellenar el rectángulo
 *                                             y delinearlo (por defecto)
 * Zend_Pdf_Page::SHAPE_DRAW_STROKE          - delinear el rectángulo
 * Zend_Pdf_Page::SHAPE_DRAW_FILL            - rellenar el rectángulo
 *
 * @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[
/**
 * Dibujar un polígono.
 *
 * Si $fillType es Zend_Pdf_Page::SHAPE_DRAW_FILL_AND_STROKE o
 * Zend_Pdf_Page::SHAPE_DRAW_FILL, entonces el polígono se cierra automáticamente.
 * Véase la descripción detallada de estos métodos en la documentación de PDF
 * (sección 4.4.2 Path painting Operators, Filling)
 *
 * @param array $x  - array de float (la coordenada X de los vértices)
 * @param array $y  - array de float (la coordenada Y de los vértices)
 * @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[
/**
 * Dibujar un círculo centrado en X, y con un radio de radius.
 *
 * Los ángulos están especificados en radianes.
 *
 * Firmas del Método::
 * drawCircle($x, $y, $radius);
 * drawCircle($x, $y, $radius, $fillType);
 * drawCircle($x, $y, $radius, $startAngle, $endAngle);
 * drawCircle($x, $y, $radius, $startAngle, $endAngle, $fillType);
 *
 *
 * No es un círculo de verdad, porque PDF sólo admite curvas cúbicss de Bezier,
 * pero con muy buena aproximación.
 * Se distingue de un verdadero círculo en un máximo de 0.00026 radios (en PI/8,
 * 3*PI/8, 5*PI/8, 7*PI/8, 9*PI/8, 11*PI/8, 13*PI/8 y 15*PI/8 ángulos).
 * A 0, PI/4, PI/2, 3*PI/4, PI, 5*PI/4, 3*PI/2 y 7*PI/4 es exactamente
 * la tangente a un círculo.
 *
 * @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[
/**
 * Dibujar una elipse dentro del rectángulo especificado.
 *
 * Firmas del método:
 * 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);
 *
 * Los ángulos se especifican en radianes
 *
 * @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>Dibujo de Texto</title>
        <para>
        Las operaciones de dibujo de texto también existen en el contexto de una 
        página PDF. Puede dibujar una sola línea de texto en cualquier posición 
        en la página mediante el suministro de las coordenadas X e Y de la base 
        de referencia. La fuente y tamaño actual de la letra se utilizan para 
        operaciones de dibujo de texto (ver descripción detallada más abajo).
        </para>
        <programlisting role="php"><![CDATA[
/**
 * Dibujar una línea de texto en una posición específica.
 *
 * @param string $text
 * @param float $x
 * @param float $y
 * @param string $charEncoding (opcional) Codificación de caracteres del texto 
 * fuente. El valor por defecto es la codificación actual y local.
 * @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>Dibujar un string en la página</title>
            <programlisting role="php"><![CDATA[
...
$pdfPage->drawText('Hello world!', 72, 720);
...
]]></programlisting>
        </example>
        <para>
        Por defecto, los strings de texto se interpretan usando el método de 
        codificación de la localización actual. Si tiene un string que utiliza  
        un método de codificación diferente (como un string UTF-8 a leer desde 
        un archivo en disco, o un string MacRoman obtenido a partir del legado 
        de una base de datos), puede indicar la codificación de caracteres a 
        llamar en tiempo de dibujo y <classname>Zend_Pdf</classname> se encargará 
        de la conversión. Puede proporcionar la fuente de cualquier método de 
        codificación de strings soportados por la función de PHP 
        <code><ulink url="http://www.php.net/manual/function.iconv.php">iconv()</ulink></code>:
        </para>
        <example id="zend.pdf.drawing.text-drawing.example-2">
            <title>Dibujar un string codificado en UTF-8 en la página</title>
            <programlisting role="php"><![CDATA[
...
// Leer del disco un string codificado en UTF-8
$unicodeString = fread($fp, 1024);

// Dibujar un string en la página
$pdfPage->drawText($unicodeString, 72, 720, 'UTF-8');
...
]]></programlisting>
        </example>
    </sect2>

    <sect2 id="zend.pdf.drawing.using-fonts">
        <title>Uso de Fuentes</title>
        <para>
        <classname>Zend_Pdf_Page::drawText()</classname> utiliza la fuente y el 
        tamaño actual de la fuente de la página, que se establece con el método
        <classname>Zend_Pdf_Page::setFont()</classname>:
        </para>
        <programlisting role="php"><![CDATA[
/**
 * Establecer la fuente actual.
 *
 * @param Zend_Pdf_Resource_Font $font
 * @param float $fontSize
 * @return Zend_Pdf_Page
 */
public function setFont(Zend_Pdf_Resource_Font $font, $fontSize);
]]></programlisting>
        <para>
        Los documentos PDF soportan fuentes PostScript Type 1 y TrueType, así 
        como dos tipos especializados de PDF, Type 3 y fuentes compuestas. 
        También hay 14 fuentes estándar Tipo 1 incorporadas para cada visor PDF: 
        Courier (4 estilos), Helvetica (4 estilos), Times (4 estilos), Symbol 
        y Zapf Dingbats.
        </para>
        <para>
        <classname>Zend_Pdf</classname> actualmente soporta el estándar de 14 
        fuentes PDF, así como sus propias fuentes personalizadas TrueType. 
        Los objetos Font se obtienen a través de una de los dos métodos de 
        fábrica: <classname>Zend_Pdf_Font::fontWithName($fontName)</classname> 
        para las 14 fuentes estándar PDF o 
        <classname>Zend_Pdf_Font::fontWithPath($filePath)</classname> para 
        fuentes personalizadas.
        </para>
        <example id="zend.pdf.drawing.using-fonts.example-1">
            <title>Crear un tipo de letra normal</title>
            <programlisting role="php"><![CDATA[
...
// Crear una fuente nueva
$font = Zend_Pdf_Font::fontWithName(Zend_Pdf_Font::FONT_HELVETICA);

// Aplicar la fuente
$pdfPage->setFont($font, 36);
...
]]></programlisting>
        </example>
        <para>
        Los nombres de las 14 constantes para el tipo de letra estándar de PDF 
        se definen en la clase <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>
        También puede utilizar cualquier fuente individual TrueType 
        (que generalmente tiene una extensión '.ttf') o bien una fuente OpenType 
        (con la extensión '.otf') si contiene esquemas TrueType. 
        Actualmente no están soportadas, pero está previsto para una versión 
        futura archivos de fuentes .dfont de Mac OS X y de Microsoft TrueType 
        Collection(extensión '.ttc').
        </para>
        <para>
        Para utilizar una fuente TrueType, debe proporcionar toda la ruta del 
        archivo a la fuente del programa. Si la fuente no se puede leer por 
        alguna razón, o si no es una fuente TrueType, el método de fábrica 
        arrojará una excepción:
        </para>
        <example id="zend.pdf.drawing.using-fonts.example-2">
            <title>Crear una fuente TrueType</title>
            <programlisting role="php"><![CDATA[
...
// Crear una nueva fuente
$goodDogCoolFont = Zend_Pdf_Font::fontWithPath('/path/to/GOODDC__.TTF');

// Aplicar la fuente
$pdfPage->setFont($goodDogCoolFont, 36);
...
]]></programlisting>
        </example>
        <para>
        Por defecto, las fuentes personalizadas serán incorporados en el 
        documento PDF resultante. Esto permite que los destinatarios vean la página 
        como está previsto, incluso si no tienen los tipos de letra apropiados 
        instalados en su sistema. Si le preocupa el tamaño del archivo, puede pedir 
        que la fuente del programa no sea integrada pasando una opción   
        'do not embed' ("no incluir") al método de fábrica:
        </para>
        <example id="zend.pdf.drawing.using-fonts.example-3">
            <title>Crear una fuente TrueType, pero no incluirla en el documento PDF.</title>
            <programlisting role="php"><![CDATA[
...
// Crear una nueva fuente
$goodDogCoolFont = Zend_Pdf_Font::fontWithPath('/path/to/GOODDC__.TTF',
                                               Zend_Pdf_Font::EMBED_DONT_EMBED);

// Aplicar la fuente
$pdfPage->setFont($goodDogCoolFont, 36);
...
]]></programlisting>
        </example>
        <para>
        Si el programa no es de fuentes incrustadas, pero el destinatario del 
        archivo PDF tiene instalada la fuente en su sistema, va a ver el 
        documento como estaba previsto. Si no tiene la fuente correcta instalada, 
        la aplicación del visor de PDF hará todo lo posible para sintetizar un sustituto.
        </para>
        <para>
        Algunas fuentes tienen normas específicas de concesión de licencias que 
        les impiden ser tenidas en cuenta en documentos PDF. Así que no son 
        capturados con la "guardia baja" por la presente, si intenta utilizar una 
        fuente que no puede ser incorporada, el método de fábrica lanzará una excepción.
        </para>
        <para>
        Puede seguir utilizando esas fuentes, pero debe pasar el flag de no 
        incluir como se ha descripto anteriormente, o simplemente puede  
        suprimir la excepción:
        </para>
        <example id="zend.pdf.drawing.using-fonts.example-4">
            <title>No arrojar una excepción para las fuentes que no puedan ser incorporadas.</title>
            <programlisting role="php"><![CDATA[
...
$font = Zend_Pdf_Font::fontWithPath(
           '/path/to/unEmbeddableFont.ttf',
           Zend_Pdf_Font::EMBED_SUPPRESS_EMBED_EXCEPTION
        );
...
]]></programlisting>
        </example>
        <para>
        Esta técnica de supresión se prefiere si va a permitir a un usuario final a 
        elegir sus propios tipos de letra. Las fuentes que puedan ser embebidas 
        en el documento PDF, lo harán, aquellos que no puedan, no.
        </para>
        <para>
        Los de programas de fuentes pueden ser bastante grandes, algunas llegan a 
        decenas de megabytes. Por defecto, todas las fuentes incorporadas son 
        comprimidas utilizando el esquema de compresión Flate, lo que resulta en 
        un ahorro de espacio del 50% en promedio. Si, por alguna razón, no 
        desea comprimir la fuente del programa, se puede desactivar con una opción:
        </para>
        <example id="zend.pdf.drawing.using-fonts.example-5">
            <title>No comprimir una fuente incrustada.</title>
            <programlisting role="php"><![CDATA[
...
$font = Zend_Pdf_Font::fontWithPath('/path/to/someReallyBigFont.ttf',
                                    Zend_Pdf_Font::EMBED_DONT_COMPRESS);
...
]]></programlisting>
        </example>
        <para>
        Por último, en caso necesario, puede combinar las opciones de la 
        integración mediante el operador binario OR:
        </para>
        <example id="zend.pdf.drawing.using-fonts.example-6">
            <title>La combinación de opciones de la incrustación de fuentes.</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>Limitaciones de las fuentes PDF estándar.</title>
        <para>
            Las fuentes estándar PDF utilizan internamente varias codificaciones 
            de un solo byte (véase <ulink url="http://www.adobe.com/devnet/acrobat/pdfs/pdf_reference_1-7.pdf">PDF Reference, Sixth Edition, version 1.7</ulink> 
            Apéndice D para más detalles). 
            Son, en general, igual al conjunto de caracteres Latin1 (excepto 
            las fuentes ZapfDingbats y Symbol).
        </para>
        <para>
            <classname>Zend_Pdf</classname> usa CP1252 (WinLatin1) para dibujar 
            el texto con las fuentes estándar.
        </para>
        <para>
            El texto todavía se puede proporcionar en cualquier otra codificación, 
            que debe ser especificada si ésta es distinto de una fuente local actual.
            Realmente, sólo se dibujarán caracteres WinLatin1.
        </para>
        <example id="zend.pdf.drawing.using-fonts.example-7">
            <title>Combinación de opciones de la incrustación de fuentes.</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>Extracción de las fuentes.</title>
        <para>
            El módulo <classname>Zend_Pdf</classname> proporciona una posibilidad 
            de extraer las fuentes de los documentos cargados.
        </para>

        <para>
            Puede ser útil para las actualizaciones incrementales de un documento. 
            Sin esta funcionalidad tiene que agregar y posiblemente, incrustar 
            una fuente en un documento cada vez que desee actualizarlo.
        </para>

        <para>
            Los objetos <classname>Zend_Pdf</classname> y <classname>Zend_Pdf_Page</classname> 
            proporcionan métodos especiales para extraer todas las fuentes 
            mencionadas en un documento o una página: 
        </para>
        <example id="zend.pdf.drawing.extracting-fonts.example-1">
            <title>Extracción de las fuentes de un documento cargado.</title>
            <programlisting role="php"><![CDATA[

...
$pdf = Zend_Pdf::load($documentPath);
...
// Obtener todas las fuentes del documento
$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 . ': The quick brown fox jumps over the lazy dog',
                    100,
                    $yPosition,
                    'UTF-8');
    $yPosition -= 30;
}
...
// Obtener las fuentes referenciadas dentro de la primera página del documento
$firstPage = reset($pdf->pages);
$firstPageFonts = $firstPage->extractFonts();
...
]]></programlisting>
        </example>
        <example id="zend.pdf.drawing.extracting-fonts.example-2">
            <title>Extracción de la fuente de un documento cargado especificando el nombre de la fuente.</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);
...
// Este nombre de fuente debe ser almacenado en algún lugar...
$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) también se puede usar aquí */
$font = $pdf->extractFont($fontName);

$page->setFont($font, $fontSize);
$page->drawText($text, $x, $y);
...
$pdf->save($docPath, true /* modo de actualización incremental */);
...
]]></programlisting>
        </example>

        <para>
            Las fuentes extraídas pueden ser utilizadas en el lugar de cualquier 
            otra fuente con las siguientes limitaciones:
            <itemizedlist>
                <listitem><para>
                La fuente extraída puede ser usada sólo en el contexto del 
                documento del que se ha extraído.
                </para></listitem>
                <listitem>
                    <para>
                        Posiblemente, el programa no extraiga realmente la fuente 
                        incrustada. Así que las fuentes extraídas no pueden 
                        proporcionar métricas correctas y la fuente original 
                        tiene que ser utilizada para los cálculos de ancho de texto:
            <programlisting role="php"><![CDATA[

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

$page->setFont($font /* usar la fuente extraída para dibujar */, $fontSize);
$xPosition = $x;
for ($charIndex = 0; $charIndex < strlen($text); $charIndex++) {
    $page->drawText($text[$charIndex], xPosition, $y);

    // Usar la fuente original para calcular el ancho del texto
    $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>Dibujo de Imágenes</title>
        <para>
        La clase <classname>Zend_Pdf_Page</classname> proporciona el método 
        drawImage() para dibujar la imagen:
        </para>
        <programlisting role="php"><![CDATA[
/**
 * Dibujar una imagen en una posición específica de la página.
 *
 * @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>
        Los objetos imagen deben ser creados con el método 
        <classname>Zend_Pdf_Image::imageWithPath($filePath)</classname>  
        (imágenes JPG, PNG y TIFF ahora son soportadas):
        </para>
        <example id="zend.pdf.drawing.image-drawing.example-1">
            <title>Dibujar una imagen</title>
            <programlisting role="php"><![CDATA[
...
// Cargar la imagen
$image = Zend_Pdf_Image::imageWithPath('my_image.jpg');

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

        <para>
            <emphasis>Importante! el soporte a JPEG requiere que se configure 
            la extensión PHP GD.</emphasis>
            <emphasis>Importante! el soporte a PNG requiere que se configure 
            la extensión ZLIB para trabajar con imágenes canal Alfa.</emphasis>
        </para>
        <para>
            Consulte la documentación de PHP para obtener información detallada 
            (<ulink url="http://www.php.net/manual/en/ref.image.php">http://www.php.net/manual/en/ref.image.php</ulink>).
            (<ulink url="http://www.php.net/manual/en/ref.zlib.php">http://www.php.net/manual/en/ref.zlib.php</ulink>).
        </para>
    </sect2>

    <sect2 id="zend.pdf.drawing.line-drawing-style">
        <title>Estilo de Dibujo de Líneas</title>
        <para>
        El estilo del dibujo de líneas está definido por el ancho de línea, 
        el color de línea y el patrón del tipo de línea. Todo esto parámetros 
        pueden ser asignados por los métodos de la clase 
        <classname>Zend_Pdf_Page</classname>:
        </para>
        <programlisting role="php"><![CDATA[
/** Establecer el color de la línea. */
public function setLineColor(Zend_Pdf_Color $color);

/** Establecer el ancho de la línea. */
public function setLineWidth(float $width);

/**
 * Establecer el patrón de líneas de guiones.
 *
 * El patrón es una array de números de punto flotante:
 *     array(on_length, off_length, on_length, off_length, ...)
 * La fase está desplazada lateralmente desde el comienzo de la línea.
 *
 * @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>Estilo Relleno</title>
        <para>
        Los métodos 
        <classname>Zend_Pdf_Page::drawRectangle()</classname>, <classname>Zend_Pdf_Page::drawPolygon()</classname>,
        <classname>Zend_Pdf_Page::drawCircle()</classname> y <classname>Zend_Pdf_Page::drawEllipse()</classname> 
        toman el argumento <code>$fillType</code> como un parámetro opcional. 
        Puede ser:
        </para>

        <itemizedlist>
            <listitem>
                <para>Zend_Pdf_Page::SHAPE_DRAW_STROKE - forma del trazo</para>
            </listitem>
            <listitem>
                <para>Zend_Pdf_Page::SHAPE_DRAW_FILL - sólo llenar la forma</para>
            </listitem>
            <listitem>
                <para>Zend_Pdf_Page::SHAPE_DRAW_FILL_AND_STROKE - llenar y trazar (comportamiento por defecto)</para>
            </listitem>
        </itemizedlist>

        <para>
        El método <classname>Zend_Pdf_Page::drawPolygon()</classname> también 
        tiene un parámetro adicional <code>$fillMethod</code>:
        </para>
        <itemizedlist>
            <listitem>
                <para>Zend_Pdf_Page::FILL_METHOD_NON_ZERO_WINDING (comportamiento por defecto)</para>
                <para>
                <citetitle>PDF reference</citetitle> esta norma se describe como sigue:
                <blockquote>
                    <para>
                        La tortuosa regla del número distinto de cero determina 
                        si un punto está dentro de un camino de un rayo conceptual 
                        dibujado a partir de ese punto hasta el infinito en 
                        cualquier dirección y luego de examinar los lugares en 
                        los que un segmento de la ruta atraviesa el rayo. 
                        A partir de la cuenta de 0, la norma agrega 1 cada vez 
                        que un segmento de ruta atraviesa el rayo de izquierda a 
                        derecha y resta 1 cada vez que un segmento cruza de derecha 
                        a izquierda. Después de contar todos los cruces, si el 
                        resultado es 0, entonces el punto está fuera del camino; 
                        otra cosa es el interior.
                    
                        Nota: El método que acabamos de describir no especifica 
                        qué hacer si un segmento de ruta coincide con o es 
                        tangente al rayo elegido. Dado que la dirección de 
                        los rayos es arbitraria, la regla simplemente elige un 
                        rayo que no encuentre problemas con las intersecciones. 
                        Por simples caminos convexos, la regla del tortuoso número 
                        distinto de cero define el dentro y afuera como uno lo  
                        espera intuitivamente. Los casos más interesantes son 
                        aquellos que involucran la complejidad o las rutas 
                        auto-intersectadas como las que se muestran en la Figura 4.10 
                        (en un PDF de referencia).

                        Para un camino que consiste en una estrella de cinco 
                        puntas, dibujado con cinco segmentos conectados de líneas 
                        rectas intersectándose entre sí, la regla considera que 
                        el interior será toda el área delimitada por la estrella, 
                        incluido el pentágono en el centro. 
                        Para un camino compuesto por dos círculos concéntricos, 
                        las áreas de ambos círculos cerrados se consideran que  
                        están adentro, siempre que ambas se hayan dibujado en 
                        la misma dirección. Si los círculos son dibujados en 
                        direcciones opuestas, sólo la forma de "doughnut" (rosquilla) 
                        formada entre ellos es el interior, de acuerdo a la norma, 
                        el "agujero de la rosquilla" está afuera.
                    </para>
                </blockquote>
                </para>
            </listitem>
            <listitem>
                <para>Zend_Pdf_Page::FILL_METHOD_EVEN_ODD</para>
                <para>
                <citetitle>PDF reference</citetitle> describe esta norma como sigue:
                <blockquote>
                    <para>
                        Una alternativa al tortuoso número distinto de cero es 
                        la regla par-impar. 
                        Esta norma determina la "interioridad" de un punto por 
                        el dibujo de un rayo desde ese punto en cualquier dirección 
                        y simplemente contando el número de segmentos de ruta 
                        que atraviesan los rayos, independientemente de la dirección. 
                        Si este número es impar, el punto está adentro, si es 
                        par, el punto está afuera. Esto produce los mismos 
                        resultados que la regla del tortuoso número distinto de cero 
                        para caminos con formas simples, pero produce resultados 
                        diferentes para formas más complejas.
                    
                        La Figura 4.11 (en un PDF de referencia) muestra los 
                        efectos de la aplicación de la regla par-impar  
                        a las rutas complejss. Para la estrella de cinco 
                        puntas, la regla considera que los puntos del triángulo  
                        están dentro de la ruta, pero no el pentágono en el centro. 
                        Para los dos círculos concéntricos, sólo la forma de la 
                        "rosquilla" entre los dos círculo está considerada 
                        adentro, independientemente de las direcciones en las 
                        que se dibujen los círculos.
                    </para>
                </blockquote>
            </para>
            </listitem>
        </itemizedlist>
    </sect2>

    <sect2 id="zend.pdf.drawing.linear-transformations">
        <title>Transformaciones Lineales</title>
        <sect3 id="zend.pdf.drawing.linear-transformations.rotations">
            <title>Rotaciones.</title>
            <para>
            La página PDF se puede rotar antes de aplicar cualquier operación 
            de dibujo. Se puede hacer con el método 
            <classname>Zend_Pdf_Page::rotate()</classname>:
            </para>
            <programlisting role="php"><![CDATA[
/**
 * Rotar la página.
 *
 * @param float $x  - la coordenada X del punto de rotación
 * @param float $y  - la coordenada Y del punto de rotación
 * @param float $angle - ángulo de rotación
 * @return Zend_Pdf_Page
 */
public function rotate($x, $y, $angle);
]]></programlisting>
        </sect3>

        <sect3 id="zend.pdf.drawing.linear-transformations.scale">
            <title>A partir de ZF 1.8, el escalado.</title>
            <para>
            La escala de transformación es proporcionada por el método: 
            <classname>Zend_Pdf_Page::scale()</classname>:
            </para>
            <programlisting role="php"><![CDATA[
/**
 * Establecer la escala al sistema de coordenadas.
 *
 * @param float $xScale - factor de escala de la dimensión X
 * @param float $yScale - factor de escala de la dimensión Y
 * @return Zend_Pdf_Page
 */
public function scale($xScale, $yScale);
]]></programlisting>
        </sect3>

        <sect3 id="zend.pdf.drawing.linear-transformations.translate">
            <title>A partir de ZF 1.8, traducir.</title>
            <para>
                El desplazamiento del sistema de coordenadas es realizado por el 
                método <classname>Zend_Pdf_Page::translate()</classname>:
            </para>
            <programlisting role="php"><![CDATA[
/**
 * Traducir sistema de coordenadas.
 *
 * @param float $xShift - desplazamiento de la coordenada X
 * @param float $yShift - desplazamiento de la coordenada Y
 * @return Zend_Pdf_Page
 */
public function translate($xShift, $yShift);
]]></programlisting>
        </sect3>

        <sect3 id="zend.pdf.drawing.linear-transformations.skew">
            <title>A partir de ZF 1.8, el sesgo.</title>
            <para>
                El sesgo de una página se puede hacer utilizando el método 
                <classname>Zend_Pdf_Page::skew()</classname>:
            </para>
            <programlisting role="php"><![CDATA[
/**
 * Traducir sistema de coordenadas.
 *
 * @param float $x  - la coordenada X del eje del punto de sesgo
 * @param float $y  - la coordenada Y del eje del punto de sesgo
 * @param float $xAngle - ángulo de sesgo en el eje X
 * @param float $yAngle - ángulo de sesgo en el eje Y
 * @return Zend_Pdf_Page
 */
public function skew($x, $y, $xAngle, $yAngle);
]]></programlisting>
        </sect3>
    </sect2>

    <sect2 id="zend.pdf.drawing.save-restore">
        <title>Guardar/Restaurar el estado de los gráficos.</title>
        <para>
            En cualquier momento el estado de la página de gráficos 
            (fuente actual, tamaño de la fuente, color de línea, color de relleno, 
            estilo de línea, rotación de la página, clip del área) se pueden 
            guardar y restaurarlos luego. 
            Guardar la operación pone los datos a un estado de pila de gráficos, 
            la operación de restauración se recupera a partir de ahí.
        </para>
        <para>
            Existen dos métodos en la clase <classname>Zend_Pdf_Page</classname> 
            para estas operaciones:
        </para>
        <programlisting role="php"><![CDATA[
/**
 * Salva el estado de los gráficos de esta página. 
 * Esta toma una instantánea del estilo aplicado actualmente, posición, 
 * área de recorte y cualquier rotación/traducción/escalado que ha sido 
 * aplicada.
 *
 * @return Zend_Pdf_Page
 */
public function saveGS();

/**
 * Restablecer los gráficos que se guardaron con la última llamada a
 * saveGS().
 *
 * @return Zend_Pdf_Page
 */
public function restoreGS();
]]></programlisting>
    </sect2>

    <sect2 id="zend.pdf.drawing.clipping">
        <title>Señalar el área de recorte</title>
        <para>
            PDF y el módulo <classname>Zend_Pdf</classname> dan soporte de recorte 
            a la zona de dibujo.
            La zona actual de Clip límita las regiones de la página de los 
            operadores afectados por la pintura. 
            En principio, es la página entera.
        </para>
        <para>
            La clase <classname>Zend_Pdf_Page</classname> proporciona un conjunto 
            de métodos para las operaciones de recorte.
        </para>
        <programlisting role="php"><![CDATA[
/**
 * Intersectar el área actual de recorte con un rectángulo.
 *
 * @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[
/**
 * Intersectar el área actual de recorte con un polígono.
 *
 * @param array $x  - array de float (la coordenada X de los vértices)
 * @param array $y  - array de float (la coordenada Y de los vértices)
 * @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[
/**
 * Intersectar el área actual de recorte con un círculo.
 *
 * @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[
/**
 * Intersectar el área actual de recorte con una elipse.
 *
 * Firmas del método:
 * drawEllipse($x1, $y1, $x2, $y2);
 * drawEllipse($x1, $y1, $x2, $y2, $startAngle, $endAngle);
 *
 * @todo process special cases with $x2-$x1 == 0 or $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>Estilos</title>
        <para>
            La clase <classname>Zend_Pdf_Style</classname> proporciona la 
            funcionalidad de los estilos.
        </para>
        <para>
            Los estilos se pueden utilizar para almacenar un conjunto de 
            parámetros de estado del gráfico y aplicarlo a un página PDF 
            por una operación:
        </para>
        <programlisting role="php"><![CDATA[
/**
 * Establecer el estilo a utilizar para futuras operaciones de dibujo sobre esta página
 *
 * @param Zend_Pdf_Style $style
 * @return Zend_Pdf_Page
 */
public function setStyle(Zend_Pdf_Style $style);

/**
 * Regresar el estilo aplicado a la página.
 *
 * @return Zend_Pdf_Style|null
 */
public function getStyle();
]]></programlisting>

        <para>
            La clase <classname>Zend_Pdf_Style</classname> proporciona un 
            conjunto de métodos para obtener o configurar diferentes parámetros 
            de estado de los gráficos:
        </para>
        <programlisting role="php"><![CDATA[
/**
 * Establecer el color de la línea.
 *
 * @param Zend_Pdf_Color $color
 * @return Zend_Pdf_Page
 */
public function setLineColor(Zend_Pdf_Color $color);
]]></programlisting>
        <programlisting role="php"><![CDATA[
/**
 * Obtener el color de la línea.
 *
 * @return Zend_Pdf_Color|null
 */
public function getLineColor();
]]></programlisting>
        <programlisting role="php"><![CDATA[
/**
 * Establecer el ancho de la línea.
 *
 * @param float $width
 * @return Zend_Pdf_Page
 */
public function setLineWidth($width);
]]></programlisting>
        <programlisting role="php"><![CDATA[
/**
 * Obtener el ancho de la línea.
 *
 * @return float
 */
public function getLineWidth();
]]></programlisting>
        <programlisting role="php"><![CDATA[
/**
 * Establecer el patrón de la línea de guiones
 *
 * @param array $pattern
 * @param float $phase
 * @return Zend_Pdf_Page
 */
public function setLineDashingPattern($pattern, $phase = 0);
]]></programlisting>
        <programlisting role="php"><![CDATA[
/**
 * Obtener el patrón de la línea de guiones
 *
 * @return array
 */
public function getLineDashingPattern();
]]></programlisting>
        <programlisting role="php"><![CDATA[
/**
 * Obtener la fase de la línea de guiones
 *
 * @return float
 */
public function getLineDashingPhase();
]]></programlisting>
        <programlisting role="php"><![CDATA[
/**
 * Establecer el color de relleno.
 *
 * @param Zend_Pdf_Color $color
 * @return Zend_Pdf_Page
 */
public function setFillColor(Zend_Pdf_Color $color);
]]></programlisting>
        <programlisting role="php"><![CDATA[
/**
 * Obtener el color de relleno.
 *
 * @return Zend_Pdf_Color|null
 */
public function getFillColor();
]]></programlisting>
        <programlisting role="php"><![CDATA[
/**
 * Establecer la fuente actual.
 *
 * @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[
/**
 * Modificar el tamaño de la fuente actual.
 *
 * @param float $fontSize
 * @return Zend_Pdf_Page
 */
public function setFontSize($fontSize);
]]></programlisting>
        <programlisting role="php"><![CDATA[
/**
 * Obtener la fuente actual.
 *
 * @return Zend_Pdf_Resource_Font $font
 */
public function getFont();
]]></programlisting>
        <programlisting role="php"><![CDATA[
/**
 * Obtener el tamaño de la fuente actual.
 *
 * @return float $fontSize
 */
public function getFontSize();
]]></programlisting>
    </sect2>

    <sect2 id="zend.pdf.drawing.alpha">
        <title>Transparencia</title>
        <para>
            El módulo <classname>Zend_Pdf</classname> soporta el manejo de la 
            transparencia.
        </para>
        <para>
            La transparencia puede ser el método 
            <classname>Zend_Pdf_Page::setAlpha()</classname>:
        <programlisting role="php"><![CDATA[

/**
 * Establecer la transparencia.
 *
 * $alpha == 0  - transparente
 * $alpha == 1  - opaco
 *
 * Modos de transparencia soportados por PDF:
 * Normal (por defecto), 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>