| blob | 76ce6eb56d569c505e6db4d3d3c61f77314aad86 |
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!-- Reviewed: no -->
3 <sect1 id="zend.pdf.interactive-features">
4 <title>Interactive Features</title>
6 <sect2 id="zend.pdf.pages.interactive-features.destinations">
7 <title>Destinations</title>
9 <para>
10 A destination defines a particular view of a document, consisting of the following
11 items:
12 </para>
14 <itemizedlist>
15 <listitem>
16 <para>The page of the document to be displayed.</para>
17 </listitem>
19 <listitem>
20 <para>The location of the document window on that page.</para>
21 </listitem>
23 <listitem>
24 <para>The magnification (zoom) factor to use when displaying the page.</para>
25 </listitem>
26 </itemizedlist>
28 <para>
29 Destinations may be associated with outline items (<link
30 linkend="zend.pdf.pages.interactive-features.outlines">Document
31 Outline (bookmarks)</link>), annotations (<link
32 linkend="zend.pdf.pages.interactive-features.annotations">Annotations</link>), or
33 actions (<link linkend="zend.pdf.pages.interactive-features.actions">Actions</link>).
34 In each case, the destination specifies the view of the document to be presented
35 when the outline item or annotation is opened or the action is performed. In addition,
36 the optional document open action can be specified.
37 </para>
39 <sect3 id="zend.pdf.pages.interactive-features.destinations.types">
40 <title>Supported Destination Types</title>
42 <para>
43 The following types are supported by <classname>Zend_Pdf</classname> component.
44 </para>
46 <sect4 id="zend.pdf.pages.interactive-features.destinations.types.zoom">
47 <title>Zend_Pdf_Destination_Zoom</title>
49 <para>
50 Display the specified page, with the coordinates (left, top) positioned at
51 the upper-left corner of the window and the contents of the page magnified
52 by the factor zoom.
53 </para>
55 <para>
56 Destination object may be created using
57 <methodname>Zend_Pdf_Destination_Zoom::create($page, $left = null, $top = null,
58 $zoom = null)</methodname>
59 method.
60 </para>
62 <para>
63 Where:
64 </para>
66 <itemizedlist>
67 <listitem>
68 <para>
69 <varname>$page</varname> is a destination page
70 (a <classname>Zend_Pdf_Page</classname> object or a page number).
71 </para>
72 </listitem>
74 <listitem>
75 <para>
76 <varname>$left</varname> is a left edge of the displayed page (float).
77 </para>
78 </listitem>
80 <listitem>
81 <para>
82 <varname>$top</varname> is a top edge of the displayed page (float).
83 </para>
84 </listitem>
86 <listitem>
87 <para>
88 <varname>$zoom</varname> is a zoom factor (float).
89 </para>
90 </listitem>
91 </itemizedlist>
93 <para>
94 <constant>NULL</constant>, specified for <varname>$left</varname>,
95 <varname>$top</varname> or <varname>$zoom</varname> parameter means
96 "current viewer application value".
97 </para>
99 <para>
100 <classname>Zend_Pdf_Destination_Zoom</classname> class also provides
101 the following methods:
102 </para>
104 <itemizedlist>
105 <listitem>
106 <para><type>Float</type><methodname>getLeftEdge()</methodname>;</para>
107 </listitem>
109 <listitem>
110 <para><methodname>setLeftEdge(float $left)</methodname>;</para>
111 </listitem>
113 <listitem>
114 <para><type>Float</type><methodname>getTopEdge()</methodname>;</para>
115 </listitem>
117 <listitem>
118 <para><methodname>setTopEdge(float $top)</methodname>;</para>
119 </listitem>
121 <listitem>
122 <para><type>Float</type><methodname>getZoomFactor()</methodname>;</para>
123 </listitem>
125 <listitem>
126 <para><methodname>setZoomFactor(float $zoom)</methodname>;</para>
127 </listitem>
128 </itemizedlist>
129 </sect4>
131 <sect4 id="zend.pdf.pages.interactive-features.destinations.types.fit">
132 <title>Zend_Pdf_Destination_Fit</title>
134 <para>
135 Display the specified page, with the coordinates (left, top) positioned at
136 the upper-left corner of the window and the contents of the page magnified
137 by the factor zoom.
138 Display the specified page, with its contents magnified just enough to fit
139 the entire page within the window both horizontally and vertically. If
140 the required horizontal and vertical magnification factors are different, use
141 the smaller of the two, centering the page within the window in the other
142 dimension.
143 </para>
145 <para>
146 Destination object may be created using
147 <methodname>Zend_Pdf_Destination_Fit::create($page)</methodname>
148 method.
149 </para>
151 <para>
152 Where <varname>$page</varname> is a destination page
153 (a <classname>Zend_Pdf_Page</classname> object or a page number).
154 </para>
155 </sect4>
157 <sect4 id="zend.pdf.pages.interactive-features.destinations.types.fit-horizontally">
158 <title>Zend_Pdf_Destination_FitHorizontally</title>
160 <para>
161 Display the specified page, with the vertical coordinate top positioned at
162 the top edge of the window and the contents of the page magnified just enough
163 to fit the entire width of the page within the window.
164 </para>
166 <para>
167 Destination object may be created using
168 <methodname>Zend_Pdf_Destination_FitHorizontally::create($page,
169 $top)</methodname> method.
170 </para>
172 <para>
173 Where:
174 </para>
176 <itemizedlist>
177 <listitem>
178 <para>
179 <varname>$page</varname> is a destination page
180 (a <classname>Zend_Pdf_Page</classname> object or a page number).
181 </para>
182 </listitem>
184 <listitem>
185 <para>
186 <varname>$top</varname> is a top edge of the displayed page
187 (float).
188 </para>
189 </listitem>
190 </itemizedlist>
192 <para>
193 <classname>Zend_Pdf_Destination_FitHorizontally</classname> class also
194 provides the following methods:
195 </para>
197 <itemizedlist>
198 <listitem>
199 <para><type>Float</type><methodname>getTopEdge()</methodname>;</para>
200 </listitem>
202 <listitem>
203 <para><methodname>setTopEdge(float $top)</methodname>;</para>
204 </listitem>
205 </itemizedlist>
206 </sect4>
208 <sect4 id="zend.pdf.pages.interactive-features.destinations.types.fit-vertically">
209 <title>Zend_Pdf_Destination_FitVertically</title>
211 <para>
212 Display the specified page, with the horizontal coordinate left positioned
213 at the left edge of the window and the contents of the page magnified just
214 enough to fit the entire height of the page within the window.
215 </para>
217 <para>
218 Destination object may be created using
219 <methodname>Zend_Pdf_Destination_FitVertically::create($page,
220 $left)</methodname> method.
221 </para>
223 <para>
224 Where:
225 </para>
227 <itemizedlist>
228 <listitem>
229 <para>
230 <varname>$page</varname> is a destination page
231 (a <classname>Zend_Pdf_Page</classname> object or a page number).
232 </para>
233 </listitem>
235 <listitem>
236 <para>
237 <varname>$left</varname> is a left edge of the displayed page
238 (float).
239 </para>
240 </listitem>
241 </itemizedlist>
243 <para>
244 <classname>Zend_Pdf_Destination_FitVertically</classname> class also
245 provides the following methods:
246 </para>
248 <itemizedlist>
249 <listitem>
250 <para><type>Float</type><methodname>getLeftEdge()</methodname>;</para>
251 </listitem>
253 <listitem>
254 <para><methodname>setLeftEdge(float $left)</methodname>;</para>
255 </listitem>
256 </itemizedlist>
257 </sect4>
259 <sect4 id="zend.pdf.pages.interactive-features.destinations.types.fit-rectangle">
260 <title>Zend_Pdf_Destination_FitRectangle</title>
262 <para>
263 Display the specified page, with its contents magnified just enough to fit
264 the rectangle specified by the coordinates left, bottom, right, and top
265 entirely within the window both horizontally and vertically. If the required
266 horizontal and vertical magnification factors are different, use the smaller
267 of the two, centering the rectangle within the window in the other dimension.
268 </para>
270 <para>
271 Destination object may be created using
272 <methodname>Zend_Pdf_Destination_FitRectangle::create($page, $left, $bottom,
273 $right, $top)</methodname> method.
274 </para>
276 <para>
277 Where:
278 </para>
280 <itemizedlist>
281 <listitem>
282 <para>
283 <varname>$page</varname> is a destination page
284 (a <classname>Zend_Pdf_Page</classname> object or a page number).
285 </para>
286 </listitem>
288 <listitem>
289 <para>
290 <varname>$left</varname> is a left edge of the displayed page
291 (float).
292 </para>
293 </listitem>
295 <listitem>
296 <para>
297 <varname>$bottom</varname> is a bottom edge of the displayed page
298 (float).
299 </para>
300 </listitem>
302 <listitem>
303 <para>
304 <varname>$right</varname> is a right edge of the displayed page (float).
305 </para>
306 </listitem>
308 <listitem>
309 <para>
310 <varname>$top</varname> is a top edge of the displayed page (float).
311 </para>
312 </listitem>
313 </itemizedlist>
315 <para>
316 <classname>Zend_Pdf_Destination_FitRectangle</classname> class also
317 provides the following methods:
318 </para>
320 <itemizedlist>
321 <listitem>
322 <para><type>Float</type><methodname>getLeftEdge()</methodname>;</para>
323 </listitem>
325 <listitem>
326 <para><methodname>setLeftEdge(float $left)</methodname>;</para>
327 </listitem>
329 <listitem>
330 <para><type>Float</type><methodname>getBottomEdge()</methodname>;</para>
331 </listitem>
333 <listitem>
334 <para><methodname>setBottomEdge(float $bottom)</methodname>;</para>
335 </listitem>
337 <listitem>
338 <para><type>Float</type><methodname>getRightEdge()</methodname>;</para>
339 </listitem>
341 <listitem>
342 <para><methodname>setRightEdge(float $right)</methodname>;</para>
343 </listitem>
345 <listitem>
346 <para><type>Float</type><methodname>getTopEdge()</methodname>;</para>
347 </listitem>
349 <listitem>
350 <para><methodname>setTopEdge(float $top)</methodname>;</para>
351 </listitem>
352 </itemizedlist>
353 </sect4>
355 <sect4 id="zend.pdf.pages.interactive-features.destinations.types.fit-bounding-box">
356 <title>Zend_Pdf_Destination_FitBoundingBox</title>
358 <para>
359 Display the specified page, with its contents magnified just enough to fit
360 its bounding box entirely within the window both horizontally and vertically.
361 If the required horizontal and vertical magnification factors are different,
362 use the smaller of the two, centering the bounding box within the window in
363 the other dimension.
364 </para>
366 <para>
367 Destination object may be created using
368 <methodname>Zend_Pdf_Destination_FitBoundingBox::create($page, $left, $bottom,
369 $right, $top)</methodname> method.
370 </para>
372 <para>
373 Where <varname>$page</varname> is a destination page
374 (a <classname>Zend_Pdf_Page</classname> object or a page number).
375 </para>
376 </sect4>
378 <sect4
379 id="zend.pdf.pages.interactive-features.destinations.types.fit-bounding-box-horizontally">
380 <title>Zend_Pdf_Destination_FitBoundingBoxHorizontally</title>
382 <para>
383 Display the specified page, with the vertical coordinate top positioned at
384 the top edge of the window and the contents of the page magnified just enough
385 to fit the entire width of its bounding box within the window.
386 </para>
388 <para>
389 Destination object may be created using
390 <methodname>Zend_Pdf_Destination_FitBoundingBoxHorizontally::create($page,
391 $top)</methodname> method.
392 </para>
394 <para>
395 Where
396 </para>
398 <itemizedlist>
399 <listitem>
400 <para>
401 <varname>$page</varname> is a destination page
402 (a <classname>Zend_Pdf_Page</classname> object or a page number).
403 </para>
404 </listitem>
406 <listitem>
407 <para>
408 <varname>$top</varname> is a top edge of the displayed page
409 (float).
410 </para>
411 </listitem>
412 </itemizedlist>
414 <para>
415 <classname>Zend_Pdf_Destination_FitBoundingBoxHorizontally</classname> class
416 also provides the following methods:
417 </para>
419 <itemizedlist>
420 <listitem>
421 <para><type>Float</type><methodname>getTopEdge()</methodname>;</para>
422 </listitem>
424 <listitem>
425 <para><methodname>setTopEdge(float $top)</methodname>;</para>
426 </listitem>
427 </itemizedlist>
428 </sect4>
430 <sect4
431 id="zend.pdf.pages.interactive-features.destinations.types.fit-bounding-box-vertically">
432 <title>Zend_Pdf_Destination_FitBoundingBoxVertically</title>
434 <para>
435 Display the specified page, with the horizontal coordinate left positioned at
436 the left edge of the window and the contents of the page magnified just
437 enough to fit the entire height of its bounding box within the window.
438 </para>
440 <para>
441 Destination object may be created using
442 <methodname>Zend_Pdf_Destination_FitBoundingBoxVertically::create($page,
443 $left)</methodname> method.
444 </para>
446 <para>
447 Where
448 </para>
450 <itemizedlist>
451 <listitem>
452 <para>
453 <varname>$page</varname> is a destination page
454 (a <classname>Zend_Pdf_Page</classname> object or a page number).
455 </para>
456 </listitem>
458 <listitem>
459 <para>
460 <varname>$left</varname> is a left edge of the displayed page
461 (float).
462 </para>
463 </listitem>
464 </itemizedlist>
466 <para>
467 <classname>Zend_Pdf_Destination_FitBoundingBoxVertically</classname> class
468 also provides the following methods:
469 </para>
471 <itemizedlist>
472 <listitem>
473 <para><type>Float</type><methodname>getLeftEdge()</methodname>;</para>
474 </listitem>
476 <listitem>
477 <para><methodname>setLeftEdge(float $left)</methodname>;</para>
478 </listitem>
479 </itemizedlist>
480 </sect4>
482 <sect4 id="zend.pdf.pages.interactive-features.destinations.types.named">
483 <title>Zend_Pdf_Destination_Named</title>
485 <para>
486 All destinations listed above are "Explicit Destinations".
487 </para>
489 <para>
490 In addition to this, <acronym>PDF</acronym> document may contain a dictionary
491 of such destinations which may be used to reference from outside the
492 <acronym>PDF</acronym> (e.g.
493 '<filename>http://www.mycompany.com/document.pdf#chapter3</filename>').
494 </para>
496 <para>
497 <classname>Zend_Pdf_Destination_Named</classname> objects allow to refer
498 destinations from the document named destinations dictionary.
499 </para>
501 <para>
502 Named destination object may be created using
503 <methodname>Zend_Pdf_Destination_Named::create(string $name)</methodname>
504 method.
505 </para>
507 <para>
508 <classname>Zend_Pdf_Destination_Named</classname> class provides the only one
509 additional method:
510 </para>
512 <para>
513 <type>String</type><methodname>getName()</methodname>;
514 </para>
515 </sect4>
516 </sect3>
518 <sect3 id="zend.pdf.pages.interactive-features.destinations.processing">
519 <title>Document level destination processing</title>
521 <para>
522 <classname>Zend_Pdf</classname> class provides a set of destinations processing
523 methods.
524 </para>
526 <para>
527 Each destination object (including named destinations) can be resolved using the
528 <methodname>resolveDestination($destination)</methodname> method. It returns
529 corresponding <classname>Zend_Pdf_Page</classname> object, if destination target
530 is found, or <constant>NULL</constant> otherwise.
531 </para>
533 <para>
534 <methodname>Zend_Pdf::resolveDestination()</methodname> method also takes
535 an optional boolean parameter <varname>$refreshPageCollectionHashes</varname>,
536 which is <constant>TRUE</constant> by default. It forces
537 <classname>Zend_Pdf</classname> object to refresh internal page collection hashes
538 since document pages list may be updated by user using
539 <varname>Zend_Pdf::$pages</varname> property
540 (<link linkend="zend.pdf.pages">Working with Pages</link>).
541 It may be turned off for performance reasons,
542 if it's known that document pages list wasn't changed since last method
543 request.
544 </para>
546 <para>
547 Complete list of named destinations can be retrieved using
548 <methodname>Zend_Pdf::getNamedDestinations()</methodname> method. It returns
549 an array of <classname>Zend_Pdf_Target</classname> objects, which are actually
550 either an explicit destination or a GoTo action
551 (<link linkend="zend.pdf.pages.interactive-features.actions">Actions</link>).
552 </para>
554 <para>
555 <methodname>Zend_Pdf::getNamedDestination(string $name)</methodname> method returns
556 specified named destination (an explicit destination or a GoTo action).
557 </para>
559 <para>
560 <acronym>PDF</acronym> document named destinations dictionary may be updated with
561 <methodname>Zend_Pdf::setNamedDestination(string $name, $destination)</methodname>
562 method, where <varname>$destination</varname> is either an explicit destination
563 (any destination except <classname>Zend_Pdf_Destination_Named</classname>) or
564 a GoTo action.
565 </para>
567 <para>
568 If <constant>NULL</constant> is specified in place of
569 <varname>$destination</varname>, then specified named destination is removed.
570 </para>
572 <note>
573 <para>
574 Unresolvable named destinations are automatically removed from a document
575 while document saving.
576 </para>
577 </note>
579 <example id="zend.pdf.interactive-features.destinations.example-1">
580 <title>Destinations usage example</title>
582 <programlisting language="php"><![CDATA[
583 $pdf = new Zend_Pdf();
584 $page1 = $pdf->newPage(Zend_Pdf_Page::SIZE_A4);
585 $page2 = $pdf->newPage(Zend_Pdf_Page::SIZE_A4);
586 $page3 = $pdf->newPage(Zend_Pdf_Page::SIZE_A4);
587 // Page created, but not included into pages list
589 $pdf->pages[] = $page1;
590 $pdf->pages[] = $page2;
592 $destination1 = Zend_Pdf_Destination_Fit::create($page2);
593 $destination2 = Zend_Pdf_Destination_Fit::create($page3);
595 // Returns $page2 object
596 $page = $pdf->resolveDestination($destination1);
598 // Returns null, page 3 is not included into document yet
599 $page = $pdf->resolveDestination($destination2);
601 $pdf->setNamedDestination('Page2', $destination1);
602 $pdf->setNamedDestination('Page3', $destination2);
604 // Returns $destination2
605 $destination = $pdf->getNamedDestination('Page3');
607 // Returns $destination1
608 $pdf->resolveDestination(Zend_Pdf_Destination_Named::create('Page2'));
610 // Returns null, page 3 is not included into document yet
611 $pdf->resolveDestination(Zend_Pdf_Destination_Named::create('Page3'));
612 ]]></programlisting>
613 </example>
614 </sect3>
615 </sect2>
617 <sect2 id="zend.pdf.pages.interactive-features.actions">
618 <title>Actions</title>
620 <para>
621 Instead of simply jumping to a destination in the document, an annotation or
622 outline item can specify an action for the viewer application to perform,
623 such as launching an application, playing a sound, or changing an annotation's
624 appearance state.
625 </para>
627 <sect3 id="zend.pdf.pages.interactive-features.actions.types">
628 <title>Supported action types</title>
630 <para>
631 The following action types are recognized while loading <acronym>PDF</acronym>
632 document:
633 </para>
635 <itemizedlist>
636 <listitem>
637 <para>
638 <classname>Zend_Pdf_Action_GoTo</classname> - go to
639 a destination in the current document.
640 </para>
641 </listitem>
643 <listitem>
644 <para>
645 <classname>Zend_Pdf_Action_GoToR</classname> - go to
646 a destination in another document.
647 </para>
648 </listitem>
650 <listitem>
651 <para>
652 <classname>Zend_Pdf_Action_GoToE</classname> - go to
653 a destination in an embedded file.
654 </para>
655 </listitem>
657 <listitem>
658 <para>
659 <classname>Zend_Pdf_Action_Launch</classname> - launch
660 an application or open or print a document.
661 </para>
662 </listitem>
664 <listitem>
665 <para>
666 <classname>Zend_Pdf_Action_Thread</classname> - begin reading
667 an article thread.
668 </para>
669 </listitem>
671 <listitem>
672 <para>
673 <classname>Zend_Pdf_Action_URI</classname> - resolve a
674 <acronym>URI</acronym>.
675 </para>
676 </listitem>
678 <listitem>
679 <para>
680 <classname>Zend_Pdf_Action_Sound</classname> - play a sound.
681 </para>
682 </listitem>
684 <listitem>
685 <para>
686 <classname>Zend_Pdf_Action_Movie</classname> - play a movie.
687 </para>
688 </listitem>
690 <listitem>
691 <para>
692 <classname>Zend_Pdf_Action_Hide</classname> - hides or shows
693 one or more annotations on the screen.
694 </para>
695 </listitem>
697 <listitem>
698 <para>
699 <classname>Zend_Pdf_Action_Named</classname> - execute an action
700 predefined by the viewer application:
701 </para>
703 <itemizedlist>
704 <listitem>
705 <para>
706 <emphasis>NextPage</emphasis> - Go to the next page
707 of the document.
708 </para>
709 </listitem>
711 <listitem>
712 <para>
713 <emphasis>PrevPage</emphasis> - Go to the previous
714 page of the document.
715 </para>
716 </listitem>
718 <listitem>
719 <para>
720 <emphasis>FirstPage</emphasis> - Go to the first page
721 of the document.
722 </para>
723 </listitem>
725 <listitem>
726 <para>
727 <emphasis>LastPage</emphasis> - Go to the last page
728 of the document.
729 </para>
730 </listitem>
731 </itemizedlist>
732 </listitem>
734 <listitem>
735 <para>
736 <classname>Zend_Pdf_Action_SubmitForm</classname> - send data to
737 a uniform resource locator.
738 </para>
739 </listitem>
741 <listitem>
742 <para>
743 <classname>Zend_Pdf_Action_ResetForm</classname> - set fields
744 to their default values.
745 </para>
746 </listitem>
748 <listitem>
749 <para>
750 <classname>Zend_Pdf_Action_ImportData</classname> - import field
751 values from a file.
752 </para>
753 </listitem>
755 <listitem>
756 <para>
757 <classname>Zend_Pdf_Action_JavaScript</classname> - execute
758 a JavaScript script.
759 </para>
760 </listitem>
762 <listitem>
763 <para>
764 <classname>Zend_Pdf_Action_SetOCGState</classname> - set the state of
765 one or more optional content groups.
766 </para>
767 </listitem>
769 <listitem>
770 <para>
771 <classname>Zend_Pdf_Action_Rendition</classname> - control the
772 playing of multimedia content (begin, stop, pause, or resume
773 a playing rendition).
774 </para>
775 </listitem>
777 <listitem>
778 <para>
779 <classname>Zend_Pdf_Action_Trans</classname> - update the display
780 of a document, using a transition dictionary.
781 </para>
782 </listitem>
784 <listitem>
785 <para>
786 <classname>Zend_Pdf_Action_GoTo3DView</classname> - set
787 the current view of a 3D annotation.
788 </para>
789 </listitem>
790 </itemizedlist>
792 <para>
793 Only <classname>Zend_Pdf_Action_GoTo</classname> and
794 <classname>Zend_Pdf_Action_URI</classname> actions can be created by
795 user now.
796 </para>
798 <para>
799 GoTo action object can be created using
800 <methodname>Zend_Pdf_Action_GoTo::create($destination)</methodname> method,
801 where <varname>$destination</varname> is a
802 <classname>Zend_Pdf_Destination</classname> object or a string which can be used
803 to identify named destination.
804 </para>
806 <para>
807 <methodname>Zend_Pdf_Action_URI::create($uri[, $isMap])</methodname> method has
808 to be used to create a URI action (see <acronym>API</acronym> documentation for the
809 details). Optional <varname>$isMap</varname> parameter is set to
810 <constant>FALSE</constant> by default.
811 </para>
813 <para>
814 It also supports the following methods:
815 </para>
816 </sect3>
818 <sect3 id="zend.pdf.pages.interactive-features.actions.chaining">
819 <title>Actions chaining</title>
821 <para>
822 Actions objects can be chained using <varname>Zend_Pdf_Action::$next</varname>
823 public property.
824 </para>
826 <para>
827 It's an array of <classname>Zend_Pdf_Action</classname> objects, which also
828 may have their sub-actions.
829 </para>
831 <para>
832 <classname>Zend_Pdf_Action</classname> class supports RecursiveIterator interface,
833 so child actions may be iterated recursively:
834 </para>
836 <programlisting language="php"><![CDATA[
837 $pdf = new Zend_Pdf();
838 $page1 = $pdf->newPage(Zend_Pdf_Page::SIZE_A4);
839 $page2 = $pdf->newPage(Zend_Pdf_Page::SIZE_A4);
840 // Page created, but not included into pages list
841 $page3 = $pdf->newPage(Zend_Pdf_Page::SIZE_A4);
843 $pdf->pages[] = $page1;
844 $pdf->pages[] = $page2;
846 $action1 = Zend_Pdf_Action_GoTo::create(
847 Zend_Pdf_Destination_Fit::create($page2));
848 $action2 = Zend_Pdf_Action_GoTo::create(
849 Zend_Pdf_Destination_Fit::create($page3));
850 $action3 = Zend_Pdf_Action_GoTo::create(
851 Zend_Pdf_Destination_Named::create('Chapter1'));
852 $action4 = Zend_Pdf_Action_GoTo::create(
853 Zend_Pdf_Destination_Named::create('Chapter5'));
855 $action2->next[] = $action3;
856 $action2->next[] = $action4;
858 $action1->next[] = $action2;
860 $actionsCount = 1; // Note! Iteration doesn't include top level action and
861 // walks through children only
862 $iterator = new RecursiveIteratorIterator(
863 $action1,
864 RecursiveIteratorIterator::SELF_FIRST);
865 foreach ($iterator as $chainedAction) {
866 $actionsCount++;
867 }
869 // Prints 'Actions in a tree: 4'
870 printf("Actions in a tree: %d\n", $actionsCount++);
871 ]]></programlisting>
872 </sect3>
874 <sect3 id="zend.pdf.pages.interactive-features.actions.open-action">
875 <title>Document Open Action</title>
877 <para>
878 Special open action may be specify a destination to be displayed or an action
879 to be performed when the document is opened.
880 </para>
882 <para>
883 <methodname>Zend_Pdf_Target Zend_Pdf::getOpenAction()</methodname> method
884 returns current document open action (or <constant>NULL</constant> if open action
885 is not set).
886 </para>
888 <para>
889 <methodname>setOpenAction(Zend_Pdf_Target $openAction = null)</methodname>
890 method sets document open action or clean it if <varname>$openAction</varname>
891 is <constant>NULL</constant>.
892 </para>
893 </sect3>
894 </sect2>
896 <sect2 id="zend.pdf.pages.interactive-features.outlines">
897 <title>Document Outline (bookmarks)</title>
899 <para>
900 A PDF document may optionally display a document outline on the screen, allowing
901 the user to navigate interactively from one part of the document to another.
902 The outline consists of a tree-structured hierarchy of outline items (sometimes
903 called bookmarks), which serve as a visual table of contents to display the document's
904 structure to the user. The user can interactively open and close individual
905 items by clicking them with the mouse. When an item is open, its immediate children
906 in the hierarchy become visible on the screen; each child may in turn be
907 open or closed, selectively revealing or hiding further parts of the hierarchy.
908 When an item is closed, all of its descendants in the hierarchy are hidden. Clicking
909 the text of any visible item activates the item, causing the viewer application to
910 jump to a destination or trigger an action associated with the item.
911 </para>
913 <para>
914 <classname>Zend_Pdf</classname> class provides public property
915 <varname>$outlines</varname> which is an array of
916 <classname>Zend_Pdf_Outline</classname> objects.
918 <programlisting language="php"><![CDATA[
919 $pdf = Zend_Pdf::load($path);
921 // Remove outline item
922 unset($pdf->outlines[0]->childOutlines[1]);
924 // Set Outline to be displayed in bold
925 $pdf->outlines[0]->childOutlines[3]->setIsBold(true);
927 // Add outline entry
928 $pdf->outlines[0]->childOutlines[5]->childOutlines[] =
929 Zend_Pdf_Outline::create('Chapter 2', 'chapter_2');
931 $pdf->save($path, true);
932 ]]></programlisting>
933 </para>
935 <para>
936 Outline attributes may be retrieved or set using the following methods:
937 </para>
939 <itemizedlist>
940 <listitem>
941 <para>
942 <methodname>string getTitle()</methodname> - get outline item title.
943 </para>
944 </listitem>
946 <listitem>
947 <para>
948 <methodname>setTitle(string $title)</methodname> - set outline item title.
949 </para>
950 </listitem>
952 <listitem>
953 <para>
954 <methodname>boolean isOpen()</methodname> - <constant>TRUE</constant> if outline
955 is open by default.
956 </para>
957 </listitem>
959 <listitem>
960 <para>
961 <methodname>setIsOpen(boolean $isOpen)</methodname> - set isOpen state.
962 </para>
963 </listitem>
965 <listitem>
966 <para>
967 <methodname>boolean isItalic()</methodname> - <constant>TRUE</constant> if
968 outline item is displayed in italic.
969 </para>
970 </listitem>
972 <listitem>
973 <para>
974 <methodname>setIsItalic(boolean $isItalic)</methodname> - set
975 isItalic state.
976 </para>
977 </listitem>
979 <listitem>
980 <para>
981 <methodname>boolean isBold()</methodname> - <constant>TRUE</constant> if outline
982 item is displayed in bold.
983 </para>
984 </listitem>
986 <listitem>
987 <para>
988 <methodname>setIsBold(boolean $isBold)</methodname> - set
989 isBold state.
990 </para>
991 </listitem>
993 <listitem>
994 <para>
995 <methodname>Zend_Pdf_Color_Rgb getColor()</methodname> - get outline
996 text color (<constant>NULL</constant> means black).
997 </para>
998 </listitem>
1000 <listitem>
1001 <para>
1002 <methodname>setColor(Zend_Pdf_Color_Rgb $color)</methodname> - set
1003 outline text color (<constant>NULL</constant> means black).
1004 </para>
1005 </listitem>
1007 <listitem>
1008 <para>
1009 <methodname>Zend_Pdf_Target getTarget()</methodname> - get outline
1010 target (action or explicit or named destination object).
1011 </para>
1012 </listitem>
1014 <listitem>
1015 <para>
1016 <methodname>setTarget(Zend_Pdf_Target|string $target)</methodname> - set
1017 outline target (action or destination). String may be used to identify
1018 named destination. <constant>NULL</constant> means 'no target'.
1019 </para>
1020 </listitem>
1022 <listitem>
1023 <para>
1024 <methodname>array getOptions()</methodname> - get outline attributes
1025 as an array.
1026 </para>
1027 </listitem>
1029 <listitem>
1030 <para>
1031 <methodname>setOptions(array $options)</methodname> - set outline options.
1032 The following options are recognized: 'title', 'open', 'color', 'italic',
1033 'bold', and 'target'.
1034 </para>
1035 </listitem>
1036 </itemizedlist>
1038 <para>
1039 New outline may be created in two ways:
1040 </para>
1042 <itemizedlist>
1043 <listitem>
1044 <para>
1045 <methodname>Zend_Pdf_Outline::create(string $title[, Zend_Pdf_Target|string
1046 $target])</methodname>
1047 </para>
1048 </listitem>
1050 <listitem>
1051 <para>
1052 <methodname>Zend_Pdf_Outline::create(array $options)</methodname>
1053 </para>
1054 </listitem>
1055 </itemizedlist>
1057 <para>
1058 Each outline object may have child outline items listed in
1059 <varname>Zend_Pdf_Outline::$childOutlines</varname> public property.
1060 It's an array of <classname>Zend_Pdf_Outline</classname> objects,
1061 so outlines are organized in a tree.
1062 </para>
1064 <para>
1065 <classname>Zend_Pdf_Outline</classname> class implements RecursiveArray interface,
1066 so child outlines may be recursively iterated using RecursiveIteratorIterator:
1067 </para>
1069 <programlisting language="php"><![CDATA[
1070 $pdf = Zend_Pdf::load($path);
1072 foreach ($pdf->outlines as $documentRootOutlineEntry) {
1073 $iterator = new RecursiveIteratorIterator(
1074 $documentRootOutlineEntry,
1075 RecursiveIteratorIterator::SELF_FIRST
1076 );
1077 foreach ($iterator as $childOutlineItem) {
1078 $OutlineItemTarget = $childOutlineItem->getTarget();
1079 if ($OutlineItemTarget instanceof Zend_Pdf_Destination) {
1080 if ($pdf->resolveDestination($OutlineItemTarget) === null) {
1081 // Mark Outline item with unresolvable destination
1082 // using RED color
1083 $childOutlineItem->setColor(new Zend_Pdf_Color_Rgb(1, 0, 0));
1084 }
1085 } else if ($OutlineItemTarget instanceof Zend_Pdf_Action_GoTo) {
1086 $OutlineItemTarget->setDestination();
1087 if ($pdf->resolveDestination($OutlineItemTarget) === null) {
1088 // Mark Outline item with unresolvable destination
1089 // using RED color
1090 $childOutlineItem->setColor(new Zend_Pdf_Color_Rgb(1, 0, 0));
1091 }
1092 }
1093 }
1094 }
1096 $pdf->save($path, true);
1097 ]]></programlisting>
1099 <note>
1100 <para>
1101 All outline items with unresolved destinations (or destinations of GoTo
1102 actions) are updated while document saving by setting their targets to
1103 <constant>NULL</constant>. So document will not be corrupted by removing pages
1104 referenced by outlines.
1105 </para>
1106 </note>
1107 </sect2>
1109 <sect2 id="zend.pdf.pages.interactive-features.annotations">
1110 <title>Annotations</title>
1112 <para>
1113 An annotation associates an object such as a note, sound, or movie with a location
1114 on a page of a PDF document, or provides a way to interact with the user by means
1115 of the mouse and keyboard.
1116 </para>
1118 <para>
1119 All annotations are represented by <classname>Zend_Pdf_Annotation</classname>
1120 abstract class.
1121 </para>
1123 <para>
1124 Annotation may be attached to a page using
1125 <methodname>Zend_Pdf_Page::attachAnnotation(Zend_Pdf_Annotation
1126 $annotation)</methodname> method.
1127 </para>
1129 <para>
1130 Three types of annotations may be created by user now:
1131 </para>
1133 <itemizedlist>
1134 <listitem>
1135 <para>
1136 <methodname>Zend_Pdf_Annotation_Link::create($x1, $y1, $x2, $y2,
1137 $target)</methodname> where <varname>$target</varname> is an action object
1138 or a destination or string (which may be used in place of named destination
1139 object).
1140 </para>
1141 </listitem>
1143 <listitem>
1144 <para>
1145 <methodname>Zend_Pdf_Annotation_Text::create($x1, $y1, $x2, $y2,
1146 $text)</methodname>
1147 </para>
1148 </listitem>
1150 <listitem>
1151 <para>
1152 <methodname>Zend_Pdf_Annotation_FileAttachment::create($x1, $y1, $x2, $y2,
1153 $fileSpecification)</methodname>
1154 </para>
1155 </listitem>
1156 </itemizedlist>
1158 <para>
1159 A link annotation represents either a hypertext link to a destination elsewhere in
1160 the document or an action to be performed.
1161 </para>
1163 <para>
1164 A text annotation represents a "sticky note" attached to a point in the PDF document.
1165 </para>
1167 <para>
1168 A file attachment annotation contains a reference to a file.
1169 </para>
1171 <para>
1172 The following methods are shared between all annotation types:
1173 </para>
1175 <itemizedlist>
1176 <listitem>
1177 <para><methodname>setLeft(float $left)</methodname></para>
1178 </listitem>
1180 <listitem>
1181 <para><methodname>float getLeft()</methodname></para>
1182 </listitem>
1184 <listitem>
1185 <para><methodname>setRight(float $right)</methodname></para>
1186 </listitem>
1188 <listitem>
1189 <para><methodname>float getRight()</methodname></para>
1190 </listitem>
1192 <listitem>
1193 <para><methodname>setTop(float $top)</methodname></para>
1194 </listitem>
1196 <listitem>
1197 <para><methodname>float getTop()</methodname></para>
1198 </listitem>
1200 <listitem>
1201 <para><methodname>setBottom(float $bottom)</methodname></para>
1202 </listitem>
1204 <listitem>
1205 <para><methodname>float getBottom()</methodname></para>
1206 </listitem>
1208 <listitem>
1209 <para><methodname>setText(string $text)</methodname></para>
1210 </listitem>
1212 <listitem>
1213 <para><methodname>string getText()</methodname></para>
1214 </listitem>
1215 </itemizedlist>
1217 <para>
1218 Text annotation property is a text to be displayed for the annotation or, if this
1219 type of annotation does not display text, an alternate description of the annotation's
1220 contents in human-readable form.
1221 </para>
1223 <para>
1224 Link annotation objects also provide two additional methods:
1225 </para>
1227 <itemizedlist>
1228 <listitem>
1229 <para>
1230 <methodname>setDestination(Zend_Pdf_Target|string $target)</methodname>
1231 </para>
1232 </listitem>
1234 <listitem>
1235 <para>
1236 <methodname>Zend_Pdf_Target getDestination()</methodname>
1237 </para>
1238 </listitem>
1239 </itemizedlist>
1240 </sect2>
1241 </sect1>
1242 <!--
1243 vim:se ts=4 sw=4 et:
1244 -->