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

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="zend.pdf.drawing">
   4     <title>Drawing</title>
   5
   6     <sect2 id="zend.pdf.drawing.geometry">
   7         <title>Geometry</title>
   8
   9         <para>
  10             <acronym>PDF</acronym> uses the same geometry as PostScript. It starts from bottom-left
  11             corner of page and by default is measured in points (1/72 of an inch).
  12         </para>
  13
  14         <para>
  15             Page size can be retrieved from a page object:
  16         </para>
  17
  18         <programlisting language="php"><![CDATA[
  19 $width  = $pdfPage->getWidth();
  20 $height = $pdfPage->getHeight();
  21 ]]></programlisting>
  22     </sect2>
  23
  24     <sect2 id="zend.pdf.drawing.color">
  25         <title>Colors</title>
  26
  27         <para>
  28             <acronym>PDF</acronym> has a powerful capabilities for colors representation.
  29             <classname>Zend_Pdf</classname> module supports Gray Scale, RGB and CMYK color spaces.
  30             Any of them can be used in any place, where <classname>Zend_Pdf_Color</classname> object
  31             is required. <classname>Zend_Pdf_Color_GrayScale</classname>,
  32             <classname>Zend_Pdf_Color_Rgb</classname> and <classname>Zend_Pdf_Color_Cmyk</classname>
  33             classes provide this functionality:
  34         </para>
  35
  36         <programlisting language="php"><![CDATA[
  37 // $grayLevel (float number). 0.0 (black) - 1.0 (white)
  38 $color1 = new Zend_Pdf_Color_GrayScale($grayLevel);
  39
  40 // $r, $g, $b (float numbers). 0.0 (min intensity) - 1.0 (max intensity)
  41 $color2 = new Zend_Pdf_Color_Rgb($r, $g, $b);
  42
  43 // $c, $m, $y, $k (float numbers). 0.0 (min intensity) - 1.0 (max intensity)
  44 $color3 = new Zend_Pdf_Color_Cmyk($c, $m, $y, $k);
  45 ]]></programlisting>
  46
  47         <para>
  48             <acronym>HTML</acronym> style colors are also provided with
  49             <classname>Zend_Pdf_Color_Html</classname> class:
  50         </para>
  51
  52         <programlisting language="php"><![CDATA[
  53 $color1 = new Zend_Pdf_Color_Html('#3366FF');
  54 $color2 = new Zend_Pdf_Color_Html('silver');
  55 $color3 = new Zend_Pdf_Color_Html('forestgreen');
  56 ]]></programlisting>
  57     </sect2>
  58
  59     <sect2 id="zend.pdf.drawing.shape-drawing">
  60         <title>Shape Drawing</title>
  61
  62         <para>
  63             All drawing operations can be done in a context of <acronym>PDF</acronym> page.
  64         </para>
  65
  66         <para>
  67             <classname>Zend_Pdf_Page</classname> class provides a set of drawing primitives:
  68         </para>
  69
  70         <programlisting language="php"><![CDATA[
  71 /**
  72  * Draw a line from x1,y1 to x2,y2.
  73  *
  74  * @param float $x1
  75  * @param float $y1
  76  * @param float $x2
  77  * @param float $y2
  78  * @return Zend_Pdf_Page
  79  */
  80 public function drawLine($x1, $y1, $x2, $y2);
  81 ]]></programlisting>
  82
  83         <programlisting language="php"><![CDATA[
  84 /**
  85  * Draw a rectangle.
  86  *
  87  * Fill types:
  88  * Zend_Pdf_Page::SHAPE_DRAW_FILL_AND_STROKE - fill rectangle
  89  *                                             and stroke (default)
  90  * Zend_Pdf_Page::SHAPE_DRAW_STROKE          - stroke rectangle
  91  * Zend_Pdf_Page::SHAPE_DRAW_FILL            - fill rectangle
  92  *
  93  * @param float $x1
  94  * @param float $y1
  95  * @param float $x2
  96  * @param float $y2
  97  * @param integer $fillType
  98  * @return Zend_Pdf_Page
  99  */
 100 public function drawRectangle($x1, $y1, $x2, $y2,
 101                     $fillType = Zend_Pdf_Page::SHAPE_DRAW_FILL_AND_STROKE);
 102 ]]></programlisting>
 103
 104         <programlisting language="php"><![CDATA[
 105 /**
 106  * Draw a rounded rectangle.
 107  *
 108  * Fill types:
 109  * Zend_Pdf_Page::SHAPE_DRAW_FILL_AND_STROKE - fill rectangle
 110  *                                             and stroke (default)
 111  * Zend_Pdf_Page::SHAPE_DRAW_STROKE      - stroke rectangle
 112  * Zend_Pdf_Page::SHAPE_DRAW_FILL        - fill rectangle
 113  *
 114  * radius is an integer representing radius of the four corners, or an array
 115  * of four integers representing the radius starting at top left, going
 116  * clockwise
 117  *
 118  * @param float $x1
 119  * @param float $y1
 120  * @param float $x2
 121  * @param float $y2
 122  * @param integer|array $radius
 123  * @param integer $fillType
 124  * @return Zend_Pdf_Page
 125  */
 126 public function drawRoundedRectangle($x1, $y1, $x2, $y2, $radius,
 127                        $fillType = Zend_Pdf_Page::SHAPE_DRAW_FILL_AND_STROKE);
 128 ]]></programlisting>
 129
 130         <programlisting language="php"><![CDATA[
 131 /**
 132  * Draw a polygon.
 133  *
 134  * If $fillType is Zend_Pdf_Page::SHAPE_DRAW_FILL_AND_STROKE or
 135  * Zend_Pdf_Page::SHAPE_DRAW_FILL, then polygon is automatically closed.
 136  * See detailed description of these methods in a PDF documentation
 137  * (section 4.4.2 Path painting Operators, Filling)
 138  *
 139  * @param array $x  - array of float (the X co-ordinates of the vertices)
 140  * @param array $y  - array of float (the Y co-ordinates of the vertices)
 141  * @param integer $fillType
 142  * @param integer $fillMethod
 143  * @return Zend_Pdf_Page
 144  */
 145 public function drawPolygon($x, $y,
 146                             $fillType =
 147                                 Zend_Pdf_Page::SHAPE_DRAW_FILL_AND_STROKE,
 148                             $fillMethod =
 149                                 Zend_Pdf_Page::FILL_METHOD_NON_ZERO_WINDING);
 150 ]]></programlisting>
 151
 152         <programlisting language="php"><![CDATA[
 153 /**
 154  * Draw a circle centered on x, y with a radius of radius.
 155  *
 156  * Angles are specified in radians
 157  *
 158  * Method signatures:
 159  * drawCircle($x, $y, $radius);
 160  * drawCircle($x, $y, $radius, $fillType);
 161  * drawCircle($x, $y, $radius, $startAngle, $endAngle);
 162  * drawCircle($x, $y, $radius, $startAngle, $endAngle, $fillType);
 163  *
 164  *
 165  * It's not a really circle, because PDF supports only cubic Bezier
 166  * curves. But very good approximation.
 167  * It differs from a real circle on a maximum 0.00026 radiuses (at PI/8,
 168  * 3*PI/8, 5*PI/8, 7*PI/8, 9*PI/8, 11*PI/8, 13*PI/8 and 15*PI/8 angles).
 169  * At 0, PI/4, PI/2, 3*PI/4, PI, 5*PI/4, 3*PI/2 and 7*PI/4 it's exactly
 170  * a tangent to a circle.
 171  *
 172  * @param float $x
 173  * @param float $y
 174  * @param float $radius
 175  * @param mixed $param4
 176  * @param mixed $param5
 177  * @param mixed $param6
 178  * @return Zend_Pdf_Page
 179  */
 180 public function  drawCircle($x,
 181                             $y,
 182                             $radius,
 183                             $param4 = null,
 184                             $param5 = null,
 185                             $param6 = null);
 186 ]]></programlisting>
 187
 188         <programlisting language="php"><![CDATA[
 189 /**
 190  * Draw an ellipse inside the specified rectangle.
 191  *
 192  * Method signatures:
 193  * drawEllipse($x1, $y1, $x2, $y2);
 194  * drawEllipse($x1, $y1, $x2, $y2, $fillType);
 195  * drawEllipse($x1, $y1, $x2, $y2, $startAngle, $endAngle);
 196  * drawEllipse($x1, $y1, $x2, $y2, $startAngle, $endAngle, $fillType);
 197  *
 198  * Angles are specified in radians
 199  *
 200  * @param float $x1
 201  * @param float $y1
 202  * @param float $x2
 203  * @param float $y2
 204  * @param mixed $param5
 205  * @param mixed $param6
 206  * @param mixed $param7
 207  * @return Zend_Pdf_Page
 208  */
 209 public function drawEllipse($x1,
 210                             $y1,
 211                             $x2,
 212                             $y2,
 213                             $param5 = null,
 214                             $param6 = null,
 215                             $param7 = null);
 216 ]]></programlisting>
 217     </sect2>
 218
 219     <sect2 id="zend.pdf.drawing.text-drawing">
 220         <title>Text Drawing</title>
 221
 222         <para>
 223             Text drawing operations also exist in the context of a <acronym>PDF</acronym> page. You
 224             can draw a single line of text at any position on the page by supplying the x and y
 225             coordinates of the baseline. Current font and current font size are used for text
 226             drawing operations (see detailed description below).
 227         </para>
 228
 229         <programlisting language="php"><![CDATA[
 230 /**
 231  * Draw a line of text at the specified position.
 232  *
 233  * @param string $text
 234  * @param float $x
 235  * @param float $y
 236  * @param string $charEncoding (optional) Character encoding of source
 237  *               text.Defaults to current locale.
 238  * @throws Zend_Pdf_Exception
 239  * @return Zend_Pdf_Page
 240  */
 241 public function drawText($text, $x, $y, $charEncoding = '');
 242 ]]></programlisting>
 243
 244         <example id="zend.pdf.drawing.text-drawing.example-1">
 245             <title>Draw a string on the page</title>
 246
 247             <programlisting language="php"><![CDATA[
 248 ...
 249 $pdfPage->drawText('Hello world!', 72, 720);
 250 ...
 251 ]]></programlisting>
 252         </example>
 253
 254         <para>
 255             By default, text strings are interpreted using the character encoding method of the
 256             current locale. if you have a string that uses a different encoding method (such as a
 257             UTF-8 string read from a file on disk, or a MacRoman string obtained from a legacy
 258             database), you can indicate the character encoding at draw time and
 259             <classname>Zend_Pdf</classname> will handle the conversion for you. You can supply
 260             source strings in any encoding method supported by <acronym>PHP</acronym>'s
 261             <code><ulink url="http://www.php.net/manual/function.iconv.php">iconv()</ulink></code>
 262             function:
 263         </para>
 264
 265         <example id="zend.pdf.drawing.text-drawing.example-2">
 266             <title>Draw a UTF-8-encoded string on the page</title>
 267
 268             <programlisting language="php"><![CDATA[
 269 ...
 270 // Read a UTF-8-encoded string from disk
 271 $unicodeString = fread($fp, 1024);
 272
 273 // Draw the string on the page
 274 $pdfPage->drawText($unicodeString, 72, 720, 'UTF-8');
 275 ...
 276 ]]></programlisting>
 277         </example>
 278     </sect2>
 279
 280     <sect2 id="zend.pdf.drawing.using-fonts">
 281         <title>Using fonts</title>
 282
 283         <para>
 284             <methodname>Zend_Pdf_Page::drawText()</methodname> uses the page's current font and font
 285             size, which is set with the <methodname>Zend_Pdf_Page::setFont()</methodname> method:
 286         </para>
 287
 288         <programlisting language="php"><![CDATA[
 289 /**
 290  * Set current font.
 291  *
 292  * @param Zend_Pdf_Resource_Font $font
 293  * @param float $fontSize
 294  * @return Zend_Pdf_Page
 295  */
 296 public function setFont(Zend_Pdf_Resource_Font $font, $fontSize);
 297 ]]></programlisting>
 298
 299         <para>
 300             <acronym>PDF</acronym> documents support PostScript Type 1 and TrueType fonts, as well
 301             as two specialized <acronym>PDF</acronym> types, Type 3 and composite fonts. There are
 302             also 14 standard Type 1 fonts built-in to every <acronym>PDF</acronym> viewer: Courier
 303             (4 styles), Helvetica (4 styles), Times (4 styles), Symbol, and Zapf Dingbats.
 304         </para>
 305
 306         <para>
 307             <classname>Zend_Pdf</classname> currently supports the standard 14
 308             <acronym>PDF</acronym> fonts as well as your own custom TrueType fonts. Font objects are
 309             obtained via one of two factory methods:
 310             <methodname>Zend_Pdf_Font::fontWithName($fontName)</methodname> for the standard 14
 311             <acronym>PDF</acronym> fonts or
 312             <methodname>Zend_Pdf_Font::fontWithPath($filePath)</methodname> for custom fonts.
 313         </para>
 314
 315         <example id="zend.pdf.drawing.using-fonts.example-1">
 316             <title>Create a standard font</title>
 317
 318             <programlisting language="php"><![CDATA[
 319 ...
 320 // Create new font
 321 $font = Zend_Pdf_Font::fontWithName(Zend_Pdf_Font::FONT_HELVETICA);
 322
 323 // Apply font
 324 $pdfPage->setFont($font, 36);
 325 ...
 326 ]]></programlisting>
 327         </example>
 328
 329         <para>
 330             Constants for the standard 14 <acronym>PDF</acronym> font names are defined in the
 331             <classname>Zend_Pdf_Font</classname> class:
 332             <itemizedlist>
 333                 <listitem><para>Zend_Pdf_Font::FONT_COURIER</para></listitem>
 334                 <listitem><para>Zend_Pdf_Font::FONT_COURIER_BOLD</para></listitem>
 335                 <listitem><para>Zend_Pdf_Font::FONT_COURIER_ITALIC</para></listitem>
 336                 <listitem><para>Zend_Pdf_Font::FONT_COURIER_BOLD_ITALIC</para></listitem>
 337                 <listitem><para>Zend_Pdf_Font::FONT_TIMES</para></listitem>
 338                 <listitem><para>Zend_Pdf_Font::FONT_TIMES_BOLD</para></listitem>
 339                 <listitem><para>Zend_Pdf_Font::FONT_TIMES_ITALIC</para></listitem>
 340                 <listitem><para>Zend_Pdf_Font::FONT_TIMES_BOLD_ITALIC</para></listitem>
 341                 <listitem><para>Zend_Pdf_Font::FONT_HELVETICA</para></listitem>
 342                 <listitem><para>Zend_Pdf_Font::FONT_HELVETICA_BOLD</para></listitem>
 343                 <listitem><para>Zend_Pdf_Font::FONT_HELVETICA_ITALIC</para></listitem>
 344                 <listitem><para>Zend_Pdf_Font::FONT_HELVETICA_BOLD_ITALIC</para></listitem>
 345                 <listitem><para>Zend_Pdf_Font::FONT_SYMBOL</para></listitem>
 346                 <listitem><para>Zend_Pdf_Font::FONT_ZAPFDINGBATS</para></listitem>
 347             </itemizedlist>
 348         </para>
 349
 350         <para>
 351             You can also use any individual TrueType font (which usually has a '.ttf' extension) or
 352             an OpenType font ('.otf' extension) if it contains TrueType outlines. Currently
 353             unsupported, but planned for a future release are Mac OS X .dfont files and Microsoft
 354             TrueType Collection ('.ttc' extension) files.
 355         </para>
 356
 357         <para>
 358             To use a TrueType font, you must provide the full file path to the font program. If the
 359             font cannot be read for some reason, or if it is not a TrueType font, the factory method
 360             will throw an exception:
 361         </para>
 362
 363         <example id="zend.pdf.drawing.using-fonts.example-2">
 364             <title>Create a TrueType font</title>
 365
 366             <programlisting language="php"><![CDATA[
 367 ...
 368 // Create new font
 369 $goodDogCoolFont = Zend_Pdf_Font::fontWithPath('/path/to/GOODDC__.TTF');
 370
 371 // Apply font
 372 $pdfPage->setFont($goodDogCoolFont, 36);
 373 ...
 374 ]]></programlisting>
 375         </example>
 376
 377         <para>
 378             By default, custom fonts will be embedded in the resulting <acronym>PDF</acronym>
 379             document. This allows recipients to view the page as intended, even if they don't have
 380             the proper fonts installed on their system. If you are concerned about file size, you
 381             can request that the font program not be embedded by passing a 'do not embed' option to
 382             the factory method:
 383         </para>
 384
 385         <example id="zend.pdf.drawing.using-fonts.example-3">
 386             <title>Create a TrueType font, but do not embed it in the PDF document</title>
 387
 388             <programlisting language="php"><![CDATA[
 389 ...
 390 // Create new font
 391 $goodDogCoolFont = Zend_Pdf_Font::fontWithPath('/path/to/GOODDC__.TTF',
 392                                                Zend_Pdf_Font::EMBED_DONT_EMBED);
 393
 394 // Apply font
 395 $pdfPage->setFont($goodDogCoolFont, 36);
 396 ...
 397 ]]></programlisting>
 398         </example>
 399
 400         <para>
 401             If the font program is not embedded but the recipient of the <acronym>PDF</acronym> file
 402             has the font installed on their system, they will see the document as intended. If they
 403             do not have the correct font installed, the <acronym>PDF</acronym> viewer application
 404             will do its best to synthesize a replacement.
 405         </para>
 406
 407         <para>
 408             Some fonts have very specific licensing rules which prevent them from being embedded in
 409             <acronym>PDF</acronym> documents. So you are not caught off-guard by this, if you try to
 410             use a font that cannot be embedded, the factory method will throw an exception.
 411         </para>
 412
 413         <para>
 414             You can still use these fonts, but you must either pass the do not embed flag as
 415             described above, or you can simply suppress the exception:
 416         </para>
 417
 418         <example id="zend.pdf.drawing.using-fonts.example-4">
 419             <title>Do not throw an exception for fonts that cannot be embedded</title>
 420
 421             <programlisting language="php"><![CDATA[
 422 ...
 423 $font = Zend_Pdf_Font::fontWithPath(
 424            '/path/to/unEmbeddableFont.ttf',
 425            Zend_Pdf_Font::EMBED_SUPPRESS_EMBED_EXCEPTION
 426         );
 427 ...
 428 ]]></programlisting>
 429         </example>
 430
 431         <para>
 432             This suppression technique is preferred if you allow an end-user to choose their own
 433             fonts. Fonts which can be embedded in the <acronym>PDF</acronym> document will be; those
 434             that cannot, won't.
 435         </para>
 436
 437         <para>
 438             Font programs can be rather large, some reaching into the tens of megabytes. By default,
 439             all embedded fonts are compressed using the Flate compression scheme, resulting in a
 440             space savings of 50% on average. If, for some reason, you do not want to compress the
 441             font program, you can disable it with an option:
 442         </para>
 443
 444         <example id="zend.pdf.drawing.using-fonts.example-5">
 445             <title>Do not compress an embedded font</title>
 446
 447             <programlisting language="php"><![CDATA[
 448 ...
 449 $font = Zend_Pdf_Font::fontWithPath('/path/to/someReallyBigFont.ttf',
 450                                     Zend_Pdf_Font::EMBED_DONT_COMPRESS);
 451 ...
 452 ]]></programlisting>
 453         </example>
 454
 455         <para>
 456             Finally, when necessary, you can combine the embedding options by using the bitwise OR
 457             operator:
 458         </para>
 459
 460         <example id="zend.pdf.drawing.using-fonts.example-6">
 461             <title>Combining font embedding options</title>
 462
 463             <programlisting language="php"><![CDATA[
 464 ...
 465 $font = Zend_Pdf_Font::fontWithPath(
 466             $someUserSelectedFontPath,
 467             (Zend_Pdf_Font::EMBED_SUPPRESS_EMBED_EXCEPTION |
 468             Zend_Pdf_Font::EMBED_DONT_COMPRESS));
 469 ...
 470 ]]></programlisting>
 471         </example>
 472     </sect2>
 473
 474     <sect2 id="zend.pdf.drawing.standard-fonts-limitations">
 475         <title>Standard PDF fonts limitations</title>
 476
 477         <para>
 478             Standard <acronym>PDF</acronym> fonts use several single byte encodings internally
 479             (see <ulink url="http://www.adobe.com/devnet/acrobat/pdfs/pdf_reference_1-7.pdf">PDF
 480                 Reference, Sixth Edition, version 1.7</ulink> Appendix D for details). They are
 481             generally equal to Latin1 character set (except Symbol and ZapfDingbats fonts).
 482         </para>
 483
 484         <para>
 485             <classname>Zend_Pdf</classname> uses CP1252 (WinLatin1) for drawing text with standard
 486             fonts.
 487         </para>
 488
 489         <para>
 490             Text still can be provided in any other encoding, which must be specified if it differs
 491             from a current locale. Only WinLatin1 characters will be actually drawn.
 492         </para>
 493
 494         <example id="zend.pdf.drawing.using-fonts.example-7">
 495             <title>Combining font embedding options</title>
 496
 497             <programlisting language="php"><![CDATA[
 498 ...
 499 $font = Zend_Pdf_Font::fontWithName(Zend_Pdf_Font::FONT_COURIER);
 500 $pdfPage->setFont($font, 36)
 501         ->drawText('Euro sign - €', 72, 720, 'UTF-8')
 502         ->drawText('Text with umlauts - à è ì', 72, 650, 'UTF-8');
 503 ...
 504 ]]></programlisting>
 505         </example>
 506     </sect2>
 507
 508     <sect2 id="zend.pdf.drawing.extracting-fonts">
 509         <title>Extracting fonts</title>
 510
 511         <para>
 512             <classname>Zend_Pdf</classname> module provides a possibility to extract fonts from
 513             loaded documents.
 514         </para>
 515
 516         <para>
 517             It may be useful for incremental document updates. Without this functionality you have
 518             to attach and possibly embed font into a document each time you want to update it.
 519         </para>
 520
 521         <para>
 522             <classname>Zend_Pdf</classname> and <classname>Zend_Pdf_Page</classname> objects provide
 523             special methods to extract all fonts mentioned within a document or a page:
 524         </para>
 525
 526         <example id="zend.pdf.drawing.extracting-fonts.example-1">
 527             <title>Extracting fonts from a loaded document</title>
 528
 529             <programlisting language="php"><![CDATA[
 530 ...
 531 $pdf = Zend_Pdf::load($documentPath);
 532 ...
 533 // Get all document fonts
 534 $fontList = $pdf->extractFonts();
 535 $pdf->pages[] = ($page = $pdf->newPage(Zend_Pdf_Page::SIZE_A4));
 536 $yPosition = 700;
 537 foreach ($fontList as $font) {
 538     $page->setFont($font, 15);
 539     $fontName = $font->getFontName(Zend_Pdf_Font::NAME_POSTSCRIPT,
 540                                    'en',
 541                                    'UTF-8');
 542     $page->drawText($fontName . ': The quick brown fox jumps over the lazy dog',
 543                     100,
 544                     $yPosition,
 545                     'UTF-8');
 546     $yPosition -= 30;
 547 }
 548 ...
 549 // Get fonts referenced within the first document page
 550 $firstPage = reset($pdf->pages);
 551 $firstPageFonts = $firstPage->extractFonts();
 552 ...
 553 ]]></programlisting>
 554         </example>
 555
 556         <example id="zend.pdf.drawing.extracting-fonts.example-2">
 557             <title>Extracting font from a loaded document by specifying font name</title>
 558
 559             <programlisting language="php"><![CDATA[
 560 ...
 561 $pdf = new Zend_Pdf();
 562 ...
 563 $pdf->pages[] = ($page = $pdf->newPage(Zend_Pdf_Page::SIZE_A4));
 564
 565 $font = Zend_Pdf_Font::fontWithPath($fontPath);
 566 $page->setFont($font, $fontSize);
 567 $page->drawText($text, $x, $y);
 568 ...
 569 // This font name should be stored somewhere...
 570 $fontName = $font->getFontName(Zend_Pdf_Font::NAME_POSTSCRIPT,
 571                                'en',
 572                                'UTF-8');
 573 ...
 574 $pdf->save($docPath);
 575 ...
 576 ]]></programlisting>
 577
 578             <programlisting language="php"><![CDATA[
 579 ...
 580 $pdf = Zend_Pdf::load($docPath);
 581 ...
 582 $pdf->pages[] = ($page = $pdf->newPage(Zend_Pdf_Page::SIZE_A4));
 583
 584 /* $srcPage->extractFont($fontName) can also be used here */
 585 $font = $pdf->extractFont($fontName);
 586
 587 $page->setFont($font, $fontSize);
 588 $page->drawText($text, $x, $y);
 589 ...
 590 $pdf->save($docPath, true /* incremental update mode */);
 591 ...
 592 ]]></programlisting>
 593         </example>
 594
 595         <para>
 596             Extracted fonts can be used in the place of any other font with the following
 597             limitations:
 598
 599             <itemizedlist>
 600                 <listitem>
 601                     <para>
 602                         Extracted font can be used only in the context of the document from which it
 603                         was extracted.
 604                     </para>
 605                 </listitem>
 606
 607                 <listitem>
 608                     <para>
 609                         Possibly embedded font program is actually not extracted. So extracted font
 610                         can't provide correct font metrics and original font has to be used for text
 611                         width calculations:
 612                     </para>
 613
 614                     <programlisting language="php"><![CDATA[
 615 ...
 616 $font = $pdf->extractFont($fontName);
 617 $originalFont = Zend_Pdf_Font::fontWithPath($fontPath);
 618
 619 $page->setFont($font /* use extracted font for drawing */, $fontSize);
 620 $xPosition = $x;
 621 for ($charIndex = 0; $charIndex < strlen($text); $charIndex++) {
 622     $page->drawText($text[$charIndex], xPosition, $y);
 623
 624     // Use original font for text width calculation
 625     $width = $originalFont->widthForGlyph(
 626                  $originalFont->glyphNumberForCharacter($text[$charIndex])
 627              );
 628     $xPosition += $width/$originalFont->getUnitsPerEm()*$fontSize;
 629 }
 630 ...
 631 ]]></programlisting>
 632                 </listitem>
 633             </itemizedlist>
 634         </para>
 635     </sect2>
 636
 637     <sect2 id="zend.pdf.drawing.image-drawing">
 638         <title>Image Drawing</title>
 639
 640         <para>
 641             <classname>Zend_Pdf_Page</classname> class provides drawImage() method to draw image:
 642         </para>
 643
 644         <programlisting language="php"><![CDATA[
 645 /**
 646  * Draw an image at the specified position on the page.
 647  *
 648  * @param Zend_Pdf_Resource_Image $image
 649  * @param float $x1
 650  * @param float $y1
 651  * @param float $x2
 652  * @param float $y2
 653  * @return Zend_Pdf_Page
 654  */
 655 public function drawImage(Zend_Pdf_Resource_Image $image, $x1, $y1, $x2, $y2);
 656 ]]></programlisting>
 657
 658         <para>
 659             Image objects should be created with
 660             <methodname>Zend_Pdf_Image::imageWithPath($filePath)</methodname> method (JPG, PNG and
 661             TIFF images are supported now):
 662         </para>
 663
 664         <example id="zend.pdf.drawing.image-drawing.example-1">
 665             <title>Image drawing</title>
 666
 667             <programlisting language="php"><![CDATA[
 668 ...
 669 // load image
 670 $image = Zend_Pdf_Image::imageWithPath('my_image.jpg');
 671
 672 $pdfPage->drawImage($image, 100, 100, 400, 300);
 673 ...
 674 ]]></programlisting>
 675         </example>
 676
 677         <para>
 678             <emphasis>Important! JPEG support requires <acronym>PHP</acronym> GD extension to be
 679                 configured.</emphasis><emphasis>Important! PNG support requires ZLIB extension to be
 680                 configured to work with Alpha channel images.</emphasis>
 681         </para>
 682
 683         <para>
 684             Refer to the <acronym>PHP</acronym> documentation for detailed information (<ulink
 685                 url="http://www.php.net/manual/en/ref.image.php">http://www.php.net/manual/en/ref.image.php</ulink>).
 686             (<ulink
 687                 url="http://www.php.net/manual/en/ref.zlib.php">http://www.php.net/manual/en/ref.zlib.php</ulink>).
 688         </para>
 689     </sect2>
 690
 691     <sect2 id="zend.pdf.drawing.line-drawing-style">
 692         <title>Line drawing style</title>
 693
 694         <para>
 695             Line drawing style is defined by line width, line color and line dashing pattern.
 696             All of this parameters can be assigned by <classname>Zend_Pdf_Page</classname>
 697             class methods:
 698         </para>
 699
 700         <programlisting language="php"><![CDATA[
 701 /** Set line color. */
 702 public function setLineColor(Zend_Pdf_Color $color);
 703
 704 /** Set line width. */
 705 public function setLineWidth(float $width);
 706
 707 /**
 708  * Set line dashing pattern.
 709  *
 710  * Pattern is an array of floats:
 711  *     array(on_length, off_length, on_length, off_length, ...)
 712  * Phase is shift from the beginning of line.
 713  *
 714  * @param array $pattern
 715  * @param array $phase
 716  * @return Zend_Pdf_Page
 717  */
 718 public function setLineDashingPattern($pattern, $phase = 0);
 719 ]]></programlisting>
 720     </sect2>
 721
 722     <sect2 id="zend.pdf.drawing.fill-style">
 723         <title>Fill style</title>
 724
 725         <para>
 726             <methodname>Zend_Pdf_Page::drawRectangle()</methodname>,
 727             <methodname>Zend_Pdf_Page::drawPolygon()</methodname>,
 728             <methodname>Zend_Pdf_Page::drawCircle()</methodname> and
 729             <methodname>Zend_Pdf_Page::drawEllipse()</methodname> methods take
 730             <varname>$fillType</varname> argument as an optional parameter. It can be:
 731         </para>
 732
 733         <itemizedlist>
 734             <listitem>
 735                 <para>Zend_Pdf_Page::SHAPE_DRAW_STROKE - stroke shape</para>
 736             </listitem>
 737
 738             <listitem>
 739                 <para>Zend_Pdf_Page::SHAPE_DRAW_FILL - only fill shape</para>
 740             </listitem>
 741
 742             <listitem>
 743                 <para>
 744                     Zend_Pdf_Page::SHAPE_DRAW_FILL_AND_STROKE - fill and stroke (default behavior)
 745                 </para>
 746             </listitem>
 747         </itemizedlist>
 748
 749         <para>
 750             <methodname>Zend_Pdf_Page::drawPolygon()</methodname> methods also takes an additional
 751             parameter <varname>$fillMethod</varname>:
 752         </para>
 753
 754         <itemizedlist>
 755             <listitem>
 756                 <para>Zend_Pdf_Page::FILL_METHOD_NON_ZERO_WINDING (default behavior)</para>
 757
 758                 <para>
 759                     <citetitle>PDF reference</citetitle> describes this rule as follows:
 760
 761                     <blockquote>
 762                         <para>
 763                             The nonzero winding number rule determines whether a given point is
 764                             inside a path by conceptually drawing a ray from that point to infinity
 765                             in any direction and then examining the places where a segment of the
 766                             path crosses the ray. Starting with a count of 0, the rule adds 1 each
 767                             time a path segment crosses the ray from left to right and subtracts 1
 768                             each time a segment crosses from right to left. After counting all the
 769                             crossings, if the result is 0 then the point is outside the path;
 770                             otherwise it is inside. Note: The method just described does not specify
 771                             what to do if a path segment coincides with or is tangent to the chosen
 772                             ray. Since the direction of the ray is arbitrary, the rule simply
 773                             chooses a ray that does not encounter such problem intersections. For
 774                             simple convex paths, the nonzero winding number rule defines the inside
 775                             and outside as one would intuitively expect. The more interesting cases
 776                             are those involving complex or self-intersecting paths like the ones
 777                             shown in Figure 4.10 (in a <acronym>PDF</acronym> Reference). For a path
 778                             consisting of a five-pointed star, drawn with five connected straight
 779                             line segments intersecting each other, the rule considers the inside to
 780                             be the entire area enclosed by the star, including the pentagon in the
 781                             center. For a path composed of two concentric circles, the areas
 782                             enclosed by both circles are considered to be inside, provided that both
 783                             are drawn in the same direction. If the circles are drawn in opposite
 784                             directions, only the "doughnut" shape between them is inside, according
 785                             to the rule; the "doughnut hole" is outside.
 786                         </para>
 787                     </blockquote>
 788                 </para>
 789             </listitem>
 790
 791             <listitem>
 792                 <para>Zend_Pdf_Page::FILL_METHOD_EVEN_ODD</para>
 793
 794                 <para>
 795                     <citetitle>PDF reference</citetitle> describes this rule as follows:
 796                     <blockquote>
 797                         <para>
 798                             An alternative to the nonzero winding number rule is the even-odd rule.
 799                             This rule determines the "insideness" of a point by drawing a ray from
 800                             that point in any direction and simply counting the number of path
 801                             segments that cross the ray, regardless of direction. If this number is
 802                             odd, the point is inside; if even, the point is outside. This yields the
 803                             same results as the nonzero winding number rule for paths with simple
 804                             shapes, but produces different results for more complex shapes. Figure
 805                             4.11 (in a <acronym>PDF</acronym> Reference) shows the effects of
 806                             applying the even-odd rule to complex paths. For the five-pointed star,
 807                             the rule considers the triangular points to be inside the path, but not
 808                             the pentagon in the center. For the two concentric circles, only the
 809                             "doughnut" shape between the two circles is considered inside,
 810                             regardless of the directions in which the circles are drawn.
 811                         </para>
 812                     </blockquote>
 813                 </para>
 814             </listitem>
 815         </itemizedlist>
 816     </sect2>
 817
 818     <sect2 id="zend.pdf.drawing.linear-transformations">
 819         <title>Linear Transformations</title>
 820
 821         <sect3 id="zend.pdf.drawing.linear-transformations.rotations">
 822             <title>Rotations</title>
 823
 824             <para>
 825                 <acronym>PDF</acronym> page can be rotated before applying any draw operation.
 826                 It can be done by <methodname>Zend_Pdf_Page::rotate()</methodname> method:
 827             </para>
 828
 829             <programlisting language="php"><![CDATA[
 830 /**
 831  * Rotate the page.
 832  *
 833  * @param float $x  - the X co-ordinate of rotation point
 834  * @param float $y  - the Y co-ordinate of rotation point
 835  * @param float $angle - rotation angle
 836  * @return Zend_Pdf_Page
 837  */
 838 public function rotate($x, $y, $angle);
 839 ]]></programlisting>
 840         </sect3>
 841
 842         <sect3 id="zend.pdf.drawing.linear-transformations.scale">
 843             <title>Starting from ZF 1.8, scaling</title>
 844
 845             <para>
 846                 Scaling transformation is provided by
 847                 <methodname>Zend_Pdf_Page::scale()</methodname> method:
 848             </para>
 849
 850             <programlisting language="php"><![CDATA[
 851 /**
 852  * Scale coordination system.
 853  *
 854  * @param float $xScale - X dimention scale factor
 855  * @param float $yScale - Y dimention scale factor
 856  * @return Zend_Pdf_Page
 857  */
 858 public function scale($xScale, $yScale);
 859 ]]></programlisting>
 860         </sect3>
 861
 862         <sect3 id="zend.pdf.drawing.linear-transformations.translate">
 863             <title>Starting from ZF 1.8, translating</title>
 864
 865             <para>
 866                 Coordinate system shifting is performed by
 867                 <methodname>Zend_Pdf_Page::translate()</methodname> method:
 868             </para>
 869
 870             <programlisting language="php"><![CDATA[
 871 /**
 872  * Translate coordination system.
 873  *
 874  * @param float $xShift - X coordinate shift
 875  * @param float $yShift - Y coordinate shift
 876  * @return Zend_Pdf_Page
 877  */
 878 public function translate($xShift, $yShift);
 879 ]]></programlisting>
 880         </sect3>
 881
 882         <sect3 id="zend.pdf.drawing.linear-transformations.skew">
 883             <title>Starting from ZF 1.8, skewing</title>
 884
 885             <para>
 886                 Page skewing can be done using <methodname>Zend_Pdf_Page::skew()</methodname>
 887                 method:
 888             </para>
 889
 890             <programlisting language="php"><![CDATA[
 891 /**
 892  * Translate coordination system.
 893  *
 894  * @param float $x  - the X co-ordinate of axis skew point
 895  * @param float $y  - the Y co-ordinate of axis skew point
 896  * @param float $xAngle - X axis skew angle
 897  * @param float $yAngle - Y axis skew angle
 898  * @return Zend_Pdf_Page
 899  */
 900 public function skew($x, $y, $xAngle, $yAngle);
 901 ]]></programlisting>
 902         </sect3>
 903     </sect2>
 904
 905     <sect2 id="zend.pdf.drawing.save-restore">
 906         <title>Save/restore graphics state</title>
 907
 908         <para>
 909             At any time page graphics state (current font, font size, line color, fill color,
 910             line style, page rotation, clip area) can be saved and then restored. Save operation
 911             puts data to a graphics state stack, restore operation retrieves it from there.
 912         </para>
 913
 914         <para>
 915             There are two methods in <classname>Zend_Pdf_Page</classname> class for these
 916             operations:
 917         </para>
 918
 919         <programlisting language="php"><![CDATA[
 920 /**
 921  * Save the graphics state of this page.
 922  * This takes a snapshot of the currently applied style, position,
 923  * clipping area and any rotation/translation/scaling that has been
 924  * applied.
 925  *
 926  * @return Zend_Pdf_Page
 927  */
 928 public function saveGS();
 929
 930 /**
 931  * Restore the graphics state that was saved with the last call to
 932  * saveGS().
 933  *
 934  * @return Zend_Pdf_Page
 935  */
 936 public function restoreGS();
 937 ]]></programlisting>
 938     </sect2>
 939
 940     <sect2 id="zend.pdf.drawing.clipping">
 941         <title>Clipping draw area</title>
 942
 943         <para>
 944             <acronym>PDF</acronym> and <classname>Zend_Pdf</classname> module support clipping of
 945             draw area. Current clip area limits the regions of the page affected by painting
 946             operators. It's a whole page initially.
 947         </para>
 948
 949         <para>
 950             <classname>Zend_Pdf_Page</classname> class provides a set of methods for clipping
 951             operations.
 952         </para>
 953
 954         <programlisting language="php"><![CDATA[
 955 /**
 956  * Intersect current clipping area with a rectangle.
 957  *
 958  * @param float $x1
 959  * @param float $y1
 960  * @param float $x2
 961  * @param float $y2
 962  * @return Zend_Pdf_Page
 963  */
 964 public function clipRectangle($x1, $y1, $x2, $y2);
 965 ]]></programlisting>
 966
 967         <programlisting language="php"><![CDATA[
 968 /**
 969  * Intersect current clipping area with a polygon.
 970  *
 971  * @param array $x  - array of float (the X co-ordinates of the vertices)
 972  * @param array $y  - array of float (the Y co-ordinates of the vertices)
 973  * @param integer $fillMethod
 974  * @return Zend_Pdf_Page
 975  */
 976 public function clipPolygon($x,
 977                             $y,
 978                             $fillMethod =
 979                                 Zend_Pdf_Page::FILL_METHOD_NON_ZERO_WINDING);
 980 ]]></programlisting>
 981
 982         <programlisting language="php"><![CDATA[
 983 /**
 984  * Intersect current clipping area with a circle.
 985  *
 986  * @param float $x
 987  * @param float $y
 988  * @param float $radius
 989  * @param float $startAngle
 990  * @param float $endAngle
 991  * @return Zend_Pdf_Page
 992  */
 993 public function clipCircle($x,
 994                            $y,
 995                            $radius,
 996                            $startAngle = null,
 997                            $endAngle = null);
 998 ]]></programlisting>
 999
1000         <programlisting language="php"><![CDATA[
1001 /**
1002  * Intersect current clipping area with an ellipse.
1003  *
1004  * Method signatures:
1005  * drawEllipse($x1, $y1, $x2, $y2);
1006  * drawEllipse($x1, $y1, $x2, $y2, $startAngle, $endAngle);
1007  *
1008  * @todo process special cases with $x2-$x1 == 0 or $y2-$y1 == 0
1009  *
1010  * @param float $x1
1011  * @param float $y1
1012  * @param float $x2
1013  * @param float $y2
1014  * @param float $startAngle
1015  * @param float $endAngle
1016  * @return Zend_Pdf_Page
1017  */
1018 public function clipEllipse($x1,
1019                             $y1,
1020                             $x2,
1021                             $y2,
1022                             $startAngle = null,
1023                             $endAngle = null);
1024 ]]></programlisting>
1025     </sect2>
1026
1027     <sect2 id="zend.pdf.drawing.styles">
1028         <title>Styles</title>
1029
1030         <para>
1031             <classname>Zend_Pdf_Style</classname> class provides styles functionality.
1032         </para>
1033
1034         <para>
1035             Styles can be used to store a set of graphic state parameters and apply it to a
1036             <acronym>PDF</acronym> page by one operation:
1037         </para>
1038
1039         <programlisting language="php"><![CDATA[
1040 /**
1041  * Set the style to use for future drawing operations on this page
1042  *
1043  * @param Zend_Pdf_Style $style
1044  * @return Zend_Pdf_Page
1045  */
1046 public function setStyle(Zend_Pdf_Style $style);
1047
1048 /**
1049  * Return the style, applied to the page.
1050  *
1051  * @return Zend_Pdf_Style|null
1052  */
1053 public function getStyle();
1054 ]]></programlisting>
1055
1056         <para>
1057             <classname>Zend_Pdf_Style</classname> class provides a set of methods to set or get
1058             different graphics state parameters:
1059         </para>
1060
1061         <programlisting language="php"><![CDATA[
1062 /**
1063  * Set line color.
1064  *
1065  * @param Zend_Pdf_Color $color
1066  * @return Zend_Pdf_Page
1067  */
1068 public function setLineColor(Zend_Pdf_Color $color);
1069 ]]></programlisting>
1070
1071         <programlisting language="php"><![CDATA[
1072 /**
1073  * Get line color.
1074  *
1075  * @return Zend_Pdf_Color|null
1076  */
1077 public function getLineColor();
1078 ]]></programlisting>
1079
1080         <programlisting language="php"><![CDATA[
1081 /**
1082  * Set line width.
1083  *
1084  * @param float $width
1085  * @return Zend_Pdf_Page
1086  */
1087 public function setLineWidth($width);
1088 ]]></programlisting>
1089
1090         <programlisting language="php"><![CDATA[
1091 /**
1092  * Get line width.
1093  *
1094  * @return float
1095  */
1096 public function getLineWidth();
1097 ]]></programlisting>
1098
1099         <programlisting language="php"><![CDATA[
1100 /**
1101  * Set line dashing pattern
1102  *
1103  * @param array $pattern
1104  * @param float $phase
1105  * @return Zend_Pdf_Page
1106  */
1107 public function setLineDashingPattern($pattern, $phase = 0);
1108 ]]></programlisting>
1109
1110         <programlisting language="php"><![CDATA[
1111 /**
1112  * Get line dashing pattern
1113  *
1114  * @return array
1115  */
1116 public function getLineDashingPattern();
1117 ]]></programlisting>
1118
1119         <programlisting language="php"><![CDATA[
1120 /**
1121  * Get line dashing phase
1122  *
1123  * @return float
1124  */
1125 public function getLineDashingPhase();
1126 ]]></programlisting>
1127
1128         <programlisting language="php"><![CDATA[
1129 /**
1130  * Set fill color.
1131  *
1132  * @param Zend_Pdf_Color $color
1133  * @return Zend_Pdf_Page
1134  */
1135 public function setFillColor(Zend_Pdf_Color $color);
1136 ]]></programlisting>
1137
1138         <programlisting language="php"><![CDATA[
1139 /**
1140  * Get fill color.
1141  *
1142  * @return Zend_Pdf_Color|null
1143  */
1144 public function getFillColor();
1145 ]]></programlisting>
1146
1147         <programlisting language="php"><![CDATA[
1148 /**
1149  * Set current font.
1150  *
1151  * @param Zend_Pdf_Resource_Font $font
1152  * @param float $fontSize
1153  * @return Zend_Pdf_Page
1154  */
1155 public function setFont(Zend_Pdf_Resource_Font $font, $fontSize);
1156 ]]></programlisting>
1157
1158         <programlisting language="php"><![CDATA[
1159 /**
1160  * Modify current font size
1161  *
1162  * @param float $fontSize
1163  * @return Zend_Pdf_Page
1164  */
1165 public function setFontSize($fontSize);
1166 ]]></programlisting>
1167
1168         <programlisting language="php"><![CDATA[
1169 /**
1170  * Get current font.
1171  *
1172  * @return Zend_Pdf_Resource_Font $font
1173  */
1174 public function getFont();
1175 ]]></programlisting>
1176
1177         <programlisting language="php"><![CDATA[
1178 /**
1179  * Get current font size
1180  *
1181  * @return float $fontSize
1182  */
1183 public function getFontSize();
1184 ]]></programlisting>
1185     </sect2>
1186
1187     <sect2 id="zend.pdf.drawing.alpha">
1188         <title>Transparency</title>
1189
1190         <para>
1191             <classname>Zend_Pdf</classname> module supports transparency handling.
1192         </para>
1193
1194         <para>
1195             Transparency may be set using <methodname>Zend_Pdf_Page::setAlpha()</methodname> method:
1196         </para>
1197
1198         <programlisting language="php"><![CDATA[
1199 /**
1200  * Set the transparency
1201  *
1202  * $alpha == 0  - transparent
1203  * $alpha == 1  - opaque
1204  *
1205  * Transparency modes, supported by PDF:
1206  * Normal (default), Multiply, Screen, Overlay, Darken, Lighten,
1207  * ColorDodge, ColorBurn, HardLight, SoftLight, Difference, Exclusion
1208  *
1209  * @param float $alpha
1210  * @param string $mode
1211  * @throws Zend_Pdf_Exception
1212  * @return Zend_Pdf_Page
1213  */
1214 public function setAlpha($alpha, $mode = 'Normal');
1215 ]]></programlisting>
1216     </sect2>
1217 </sect1>