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

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

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

        <para>
            <acronym>PDF</acronym> uses the same geometry as PostScript. It starts from bottom-left
            corner of page and by default is measured in points (1/72 of an inch).
        </para>

        <para>
            Page size can be retrieved from a page object:
        </para>

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

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

        <para>
            <acronym>PDF</acronym> has a powerful capabilities for colors representation.
            <classname>Zend_Pdf</classname> module supports Gray Scale, RGB and CMYK color spaces.
            Any of them can be used in any place, where <classname>Zend_Pdf_Color</classname> object
            is required. <classname>Zend_Pdf_Color_GrayScale</classname>,
            <classname>Zend_Pdf_Color_Rgb</classname> and <classname>Zend_Pdf_Color_Cmyk</classname>
            classes provide this functionality:
        </para>

        <programlisting language="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>
            HTML style colors are also provided with <classname>Zend_Pdf_Color_Html</classname>
            class:
        </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>Shape Drawing</title>

        <para>
            All drawing operations can be done in a context of <acronym>PDF</acronym> page.
        </para>

        <para>
            <classname>Zend_Pdf_Page</classname> class provides a set of drawing primitives:
        </para>

        <programlisting language="php"><![CDATA[
/**
 * Draw a line from x1,y1 to 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[
/**
 * Draw a rectangle.
 *
 * Fill types:
 * Zend_Pdf_Page::SHAPE_DRAW_FILL_AND_STROKE - fill rectangle
 *                                             and stroke (default)
 * Zend_Pdf_Page::SHAPE_DRAW_STROKE          - stroke rectangle
 * Zend_Pdf_Page::SHAPE_DRAW_FILL            - fill rectangle
 *
 * @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[
/**
 * Draw a rounded rectangle.
 *
 * Fill types:
 * Zend_Pdf_Page::SHAPE_DRAW_FILL_AND_STROKE - fill rectangle and stroke (default)
 * Zend_Pdf_Page::SHAPE_DRAW_STROKE      - stroke rectangle
 * Zend_Pdf_Page::SHAPE_DRAW_FILL        - fill rectangle
 *
 * radius is an integer representing radius of the four corners, or an array
 * of four integers representing the radius starting at top left, going
 * clockwise
 *
 * @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[
/**
 * Draw a polygon.
 *
 * If $fillType is Zend_Pdf_Page::SHAPE_DRAW_FILL_AND_STROKE or
 * Zend_Pdf_Page::SHAPE_DRAW_FILL, then polygon is automatically closed.
 * See detailed description of these methods in a PDF documentation
 * (section 4.4.2 Path painting Operators, Filling)
 *
 * @param array $x  - array of float (the X co-ordinates of the vertices)
 * @param array $y  - array of float (the Y co-ordinates of the vertices)
 * @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[
/**
 * Draw a circle centered on x, y with a radius of radius.
 *
 * Angles are specified in radians
 *
 * Method signatures:
 * drawCircle($x, $y, $radius);
 * drawCircle($x, $y, $radius, $fillType);
 * drawCircle($x, $y, $radius, $startAngle, $endAngle);
 * drawCircle($x, $y, $radius, $startAngle, $endAngle, $fillType);
 *
 *
 * It's not a really circle, because PDF supports only cubic Bezier
 * curves. But very good approximation.
 * It differs from a real circle on a maximum 0.00026 radiuses (at PI/8,
 * 3*PI/8, 5*PI/8, 7*PI/8, 9*PI/8, 11*PI/8, 13*PI/8 and 15*PI/8 angles).
 * At 0, PI/4, PI/2, 3*PI/4, PI, 5*PI/4, 3*PI/2 and 7*PI/4 it's exactly
 * a tangent to a circle.
 *
 * @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[
/**
 * Draw an ellipse inside the specified rectangle.
 *
 * Method signatures:
 * 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);
 *
 * Angles are specified in 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>
    </sect2>

    <sect2 id="zend.pdf.drawing.text-drawing">
        <title>Text Drawing</title>

        <para>
            Text drawing operations also exist in the context of a <acronym>PDF</acronym> page. You
            can draw a single line of text at any position on the page by supplying the x and y
            coordinates of the baseline. Current font and current font size are used for text
            drawing operations (see detailed description below).
        </para>

        <programlisting language="php"><![CDATA[
/**
 * Draw a line of text at the specified position.
 *
 * @param string $text
 * @param float $x
 * @param float $y
 * @param string $charEncoding (optional) Character encoding of source
 *               text.Defaults to current 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>Draw a string on the page</title>

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

        <para>
            By default, text strings are interpreted using the character encoding method of the
            current locale. if you have a string that uses a different encoding method (such as a
            UTF-8 string read from a file on disk, or a MacRoman string obtained from a legacy
            database), you can indicate the character encoding at draw time and
            <classname>Zend_Pdf</classname> will handle the conversion for you. You can supply
            source strings in any encoding method supported by <acronym>PHP</acronym>'s
            <code><ulink url="http://www.php.net/manual/function.iconv.php">iconv()</ulink></code>
            function:
        </para>

        <example id="zend.pdf.drawing.text-drawing.example-2">
            <title>Draw a UTF-8-encoded string on the page</title>

            <programlisting language="php"><![CDATA[
...
// Read a UTF-8-encoded string from disk
$unicodeString = fread($fp, 1024);

// Draw the string on the page
$pdfPage->drawText($unicodeString, 72, 720, 'UTF-8');
...
]]></programlisting>
        </example>
    </sect2>

    <sect2 id="zend.pdf.drawing.using-fonts">
        <title>Using fonts</title>

        <para>
            <methodname>Zend_Pdf_Page::drawText()</methodname> uses the page's current font and font
            size, which is set with the <methodname>Zend_Pdf_Page::setFont()</methodname> method:
        </para>

        <programlisting language="php"><![CDATA[
/**
 * Set current font.
 *
 * @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> documents support PostScript Type 1 and TrueType fonts, as well
            as two specialized <acronym>PDF</acronym> types, Type 3 and composite fonts. There are
            also 14 standard Type 1 fonts built-in to every <acronym>PDF</acronym> viewer: Courier
            (4 styles), Helvetica (4 styles), Times (4 styles), Symbol, and Zapf Dingbats.
        </para>

        <para>
            <classname>Zend_Pdf</classname> currently supports the standard 14
            <acronym>PDF</acronym> fonts as well as your own custom TrueType fonts. Font objects are
            obtained via one of two factory methods:
            <methodname>Zend_Pdf_Font::fontWithName($fontName)</methodname> for the standard 14
            <acronym>PDF</acronym> fonts or
            <methodname>Zend_Pdf_Font::fontWithPath($filePath)</methodname> for custom fonts.
        </para>

        <example id="zend.pdf.drawing.using-fonts.example-1">
            <title>Create a standard font</title>

            <programlisting language="php"><![CDATA[
...
// Create new font
$font = Zend_Pdf_Font::fontWithName(Zend_Pdf_Font::FONT_HELVETICA);

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

        <para>
            Constants for the standard 14 <acronym>PDF</acronym> font names are defined in the
            <classname>Zend_Pdf_Font</classname> class:
            <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>
            You can also use any individual TrueType font (which usually has a '.ttf' extension) or
            an OpenType font ('.otf' extension) if it contains TrueType outlines. Currently
            unsupported, but planned for a future release are Mac OS X .dfont files and Microsoft
            TrueType Collection ('.ttc' extension) files.
        </para>

        <para>
            To use a TrueType font, you must provide the full file path to the font program. If the
            font cannot be read for some reason, or if it is not a TrueType font, the factory method
            will throw an exception:
        </para>

        <example id="zend.pdf.drawing.using-fonts.example-2">
            <title>Create a TrueType font</title>

            <programlisting language="php"><![CDATA[
...
// Create new font
$goodDogCoolFont = Zend_Pdf_Font::fontWithPath('/path/to/GOODDC__.TTF');

// Apply font
$pdfPage->setFont($goodDogCoolFont, 36);
...
]]></programlisting>
        </example>

        <para>
            By default, custom fonts will be embedded in the resulting <acronym>PDF</acronym>
            document. This allows recipients to view the page as intended, even if they don't have
            the proper fonts installed on their system. If you are concerned about file size, you
            can request that the font program not be embedded by passing a 'do not embed' option to
            the factory method:
        </para>

        <example id="zend.pdf.drawing.using-fonts.example-3">
            <title>Create a TrueType font, but do not embed it in the PDF document</title>

            <programlisting language="php"><![CDATA[
...
// Create new font
$goodDogCoolFont = Zend_Pdf_Font::fontWithPath('/path/to/GOODDC__.TTF',
                                               Zend_Pdf_Font::EMBED_DONT_EMBED);

// Apply font
$pdfPage->setFont($goodDogCoolFont, 36);
...
]]></programlisting>
        </example>

        <para>
            If the font program is not embedded but the recipient of the <acronym>PDF</acronym> file
            has the font installed on their system, they will see the document as intended. If they
            do not have the correct font installed, the <acronym>PDF</acronym> viewer application
            will do its best to synthesize a replacement.
        </para>

        <para>
            Some fonts have very specific licensing rules which prevent them from being embedded in
            <acronym>PDF</acronym> documents. So you are not caught off-guard by this, if you try to
            use a font that cannot be embedded, the factory method will throw an exception.
        </para>

        <para>
            You can still use these fonts, but you must either pass the do not embed flag as
            described above, or you can simply suppress the exception:
        </para>

        <example id="zend.pdf.drawing.using-fonts.example-4">
            <title>Do not throw an exception for fonts that cannot be embedded</title>

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

        <para>
            This suppression technique is preferred if you allow an end-user to choose their own
            fonts. Fonts which can be embedded in the <acronym>PDF</acronym> document will be; those
            that cannot, won't.
        </para>

        <para>
            Font programs can be rather large, some reaching into the tens of megabytes. By default,
            all embedded fonts are compressed using the Flate compression scheme, resulting in a
            space savings of 50% on average. If, for some reason, you do not want to compress the
            font program, you can disable it with an option:
        </para>

        <example id="zend.pdf.drawing.using-fonts.example-5">
            <title>Do not compress an embedded font</title>

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

        <para>
            Finally, when necessary, you can combine the embedding options by using the bitwise OR
            operator:
        </para>

        <example id="zend.pdf.drawing.using-fonts.example-6">
            <title>Combining font embedding options</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>Standard PDF fonts limitations</title>

        <para>
            Standard <acronym>PDF</acronym> fonts use several single byte encodings internally
            (see <ulink url="http://www.adobe.com/devnet/acrobat/pdfs/pdf_reference_1-7.pdf">PDF
                Reference, Sixth Edition, version 1.7</ulink> Appendix D for details). They are
            generally equal to Latin1 character set (except Symbol and ZapfDingbats fonts).
        </para>

        <para>
            <classname>Zend_Pdf</classname> uses CP1252 (WinLatin1) for drawing text with standard
            fonts.
        </para>

        <para>
            Text still can be provided in any other encoding, which must be specified if it differs
            from a current locale. Only WinLatin1 characters will be actually drawn.
        </para>

        <example id="zend.pdf.drawing.using-fonts.example-7">
            <title>Combining font embedding options</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>Extracting fonts</title>

        <para>
            <classname>Zend_Pdf</classname> module provides a possibility to extract fonts from
            loaded documents.
        </para>

        <para>
            It may be useful for incremental document updates. Without this functionality you have
            to attach and possibly embed font into a document each time you want to update it.
        </para>

        <para>
            <classname>Zend_Pdf</classname> and <classname>Zend_Pdf_Page</classname> objects provide
            special methods to extract all fonts mentioned within a document or a page:
        </para>

        <example id="zend.pdf.drawing.extracting-fonts.example-1">
            <title>Extracting fonts from a loaded document</title>

            <programlisting language="php"><![CDATA[
...
$pdf = Zend_Pdf::load($documentPath);
...
// Get all document fonts
$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;
}
...
// Get fonts referenced within the first document page
$firstPage = reset($pdf->pages);
$firstPageFonts = $firstPage->extractFonts();
...
]]></programlisting>
        </example>

        <example id="zend.pdf.drawing.extracting-fonts.example-2">
            <title>Extracting font from a loaded document by specifying font name</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);
...
// This font name should be stored somewhere...
$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) can also be used here */
$font = $pdf->extractFont($fontName);

$page->setFont($font, $fontSize);
$page->drawText($text, $x, $y);
...
$pdf->save($docPath, true /* incremental update mode */);
...
]]></programlisting>
        </example>

        <para>
            Extracted fonts can be used in the place of any other font with the following
            limitations:

            <itemizedlist>
                <listitem>
                    <para>
                        Extracted font can be used only in the context of the document from which it
                        was extracted.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        Possibly embedded font program is actually not extracted. So extracted font
                        can't provide correct font metrics and original font has to be used for text
                        width calculations:

                        <programlisting language="php"><![CDATA[
...
$font = $pdf->extractFont($fontName);
$originalFont = Zend_Pdf_Font::fontWithPath($fontPath);

$page->setFont($font /* use extracted font for drawing */, $fontSize);
$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()*$fontSize;
}
...
]]></programlisting>
                    </para>
                </listitem>
            </itemizedlist>
        </para>
    </sect2>

    <sect2 id="zend.pdf.drawing.image-drawing">
        <title>Image Drawing</title>

        <para>
            <classname>Zend_Pdf_Page</classname> class provides drawImage() method to draw image:
        </para>

        <programlisting language="php"><![CDATA[
/**
 * Draw an image at the specified position on the 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>
            Image objects should be created with
            <methodname>Zend_Pdf_Image::imageWithPath($filePath)</methodname> method (JPG, PNG and
            TIFF images are supported now):
        </para>

        <example id="zend.pdf.drawing.image-drawing.example-1">
            <title>Image drawing</title>

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

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

        <para>
            <emphasis>Important! JPEG support requires <acronym>PHP</acronym> GD extension to be
                configured.</emphasis><emphasis>Important! PNG support requires ZLIB extension to be
                configured to work with Alpha channel images.</emphasis>
        </para>

        <para>
            Refer to the <acronym>PHP</acronym> documentation for detailed information (<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>Line drawing style</title>

        <para>
            Line drawing style is defined by line width, line color and line dashing pattern.
            All of this parameters can be assigned by <classname>Zend_Pdf_Page</classname>
            class methods:
        </para>

        <programlisting language="php"><![CDATA[
/** Set line color. */
public function setLineColor(Zend_Pdf_Color $color);

/** Set line width. */
public function setLineWidth(float $width);

/**
 * Set line dashing pattern.
 *
 * Pattern is an array of floats:
 *     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>Fill style</title>

        <para>
            <methodname>Zend_Pdf_Page::drawRectangle()</methodname>,
            <methodname>Zend_Pdf_Page::drawPolygon()</methodname>,
            <methodname>Zend_Pdf_Page::drawCircle()</methodname> and
            <methodname>Zend_Pdf_Page::drawEllipse()</methodname> methods take
            <varname>$fillType</varname> argument as an optional parameter. It can be:
        </para>

        <itemizedlist>
            <listitem>
                <para>Zend_Pdf_Page::SHAPE_DRAW_STROKE - stroke shape</para>
            </listitem>

            <listitem>
                <para>Zend_Pdf_Page::SHAPE_DRAW_FILL - only fill shape</para>
            </listitem>

            <listitem>
                <para>
                    Zend_Pdf_Page::SHAPE_DRAW_FILL_AND_STROKE - fill and stroke (default behavior)
                </para>
            </listitem>
        </itemizedlist>

        <para>
            <methodname>Zend_Pdf_Page::drawPolygon()</methodname> methods also takes an additional
            parameter <varname>$fillMethod</varname>:
        </para>

        <itemizedlist>
            <listitem>
                <para>Zend_Pdf_Page::FILL_METHOD_NON_ZERO_WINDING (default behavior)</para>

                <para>
                    <citetitle>PDF reference</citetitle> describes this rule as follows:

                    <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>
                    <citetitle>PDF reference</citetitle> describes this rule as follows:
                    <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>Linear Transformations</title>

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

            <para>
                <acronym>PDF</acronym> page can be rotated before applying any draw operation.
                It can be done by <methodname>Zend_Pdf_Page::rotate()</methodname> method:
            </para>

            <programlisting language="php"><![CDATA[
/**
 * Rotate the page.
 *
 * @param float $x  - the X co-ordinate of rotation point
 * @param float $y  - the Y co-ordinate of rotation point
 * @param float $angle - rotation angle
 * @return Zend_Pdf_Page
 */
public function rotate($x, $y, $angle);
]]></programlisting>
        </sect3>

        <sect3 id="zend.pdf.drawing.linear-transformations.scale">
            <title>Starting from ZF 1.8, scaling</title>

            <para>
                Scaling transformation is provided by
                <methodname>Zend_Pdf_Page::scale()</methodname> method:
            </para>

            <programlisting language="php"><![CDATA[
/**
 * Scale coordination system.
 *
 * @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>Starting from ZF 1.8, translating</title>

            <para>
                Coordinate system shifting is performed by
                <methodname>Zend_Pdf_Page::translate()</methodname> method:
            </para>

            <programlisting language="php"><![CDATA[
/**
 * Translate coordination system.
 *
 * @param float $xShift - X coordinate shift
 * @param float $yShift - Y coordinate shift
 * @return Zend_Pdf_Page
 */
public function translate($xShift, $yShift);
]]></programlisting>
        </sect3>

        <sect3 id="zend.pdf.drawing.linear-transformations.skew">
            <title>Starting from ZF 1.8, skewing</title>

            <para>
                Page skewing can be done using <methodname>Zend_Pdf_Page::skew()</methodname>
                method:
            </para>

            <programlisting language="php"><![CDATA[
/**
 * Translate coordination system.
 *
 * @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>Save/restore graphics state</title>

        <para>
            At any time page graphics state (current font, font size, line color, fill color,
            line style, page rotation, clip area) can be saved and then restored. Save operation
            puts data to a graphics state stack, restore operation retrieves it from there.
        </para>

        <para>
            There are two methods in <classname>Zend_Pdf_Page</classname> class for these
            operations:
        </para>

        <programlisting language="php"><![CDATA[
/**
 * Save the graphics state of this page.
 * This takes a snapshot of the currently applied style, position,
 * clipping area and any rotation/translation/scaling that has been
 * applied.
 *
 * @return Zend_Pdf_Page
 */
public function saveGS();

/**
 * Restore the graphics state that was saved with the last call to
 * saveGS().
 *
 * @return Zend_Pdf_Page
 */
public function restoreGS();
]]></programlisting>
    </sect2>

    <sect2 id="zend.pdf.drawing.clipping">
        <title>Clipping draw area</title>

        <para>
            <acronym>PDF</acronym> and <classname>Zend_Pdf</classname> module support clipping of
            draw area. Current clip area limits the regions of the page affected by painting
            operators. It's a whole page initially.
        </para>

        <para>
            <classname>Zend_Pdf_Page</classname> class provides a set of methods for clipping
            operations.
        </para>

        <programlisting language="php"><![CDATA[
/**
 * Intersect current clipping area with a 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>

        <programlisting language="php"><![CDATA[
/**
 * Intersect current clipping area with a polygon.
 *
 * @param array $x  - array of float (the X co-ordinates of the vertices)
 * @param array $y  - array of float (the Y co-ordinates of the vertices)
 * @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[
/**
 * Intersect current clipping area with a circle.
 *
 * @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[
/**
 * Intersect current clipping area with an ellipse.
 *
 * Method signatures:
 * 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>Styles</title>

        <para>
            <classname>Zend_Pdf_Style</classname> class provides styles functionality.
        </para>

        <para>
            Styles can be used to store a set of graphic state parameters and apply it to a
            <acronym>PDF</acronym> page by one operation:
        </para>

        <programlisting language="php"><![CDATA[
/**
 * Set the style to use for future drawing operations on this page
 *
 * @param Zend_Pdf_Style $style
 * @return Zend_Pdf_Page
 */
public function setStyle(Zend_Pdf_Style $style);

/**
 * Return the style, applied to the page.
 *
 * @return Zend_Pdf_Style|null
 */
public function getStyle();
]]></programlisting>

        <para>
            <classname>Zend_Pdf_Style</classname> class provides a set of methods to set or get
            different graphics state parameters:
        </para>

        <programlisting language="php"><![CDATA[
/**
 * Set line color.
 *
 * @param Zend_Pdf_Color $color
 * @return Zend_Pdf_Page
 */
public function setLineColor(Zend_Pdf_Color $color);
]]></programlisting>

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

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

        <programlisting language="php"><![CDATA[
/**
 * Get line width.
 *
 * @return float
 */
public function getLineWidth();
]]></programlisting>

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

        <programlisting language="php"><![CDATA[
/**
 * Get line dashing pattern
 *
 * @return array
 */
public function getLineDashingPattern();
]]></programlisting>

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

        <programlisting language="php"><![CDATA[
/**
 * Set fill color.
 *
 * @param Zend_Pdf_Color $color
 * @return Zend_Pdf_Page
 */
public function setFillColor(Zend_Pdf_Color $color);
]]></programlisting>

        <programlisting language="php"><![CDATA[
/**
 * Get fill color.
 *
 * @return Zend_Pdf_Color|null
 */
public function getFillColor();
]]></programlisting>

        <programlisting language="php"><![CDATA[
/**
 * Set current font.
 *
 * @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[
/**
 * Modify current font size
 *
 * @param float $fontSize
 * @return Zend_Pdf_Page
 */
public function setFontSize($fontSize);
]]></programlisting>

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

        <programlisting language="php"><![CDATA[
/**
 * Get current font size
 *
 * @return float $fontSize
 */
public function getFontSize();
]]></programlisting>
    </sect2>

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

        <para>
            <classname>Zend_Pdf</classname> module supports transparency handling.
        </para>

        <para>
            Transparency may be set using <methodname>Zend_Pdf_Page::setAlpha()</methodname> method:

            <programlisting language="php"><![CDATA[
/**
 * Set the transparency
 *
 * $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>