# Interaktive Features

## Ziele

Ein Ziel definiert eine spezielle Sicht eines Dokuments, bestehend aus den folgenden Elementen:

- Die Seite des Dokuments das angezeigt werden soll.

- Der Ort des Dokumenten Fensters auf dieser Seite.

- Der Zoom Faktor der verwendet werden soll wenn die Seite angezeigt wird.

Ziele können mit Outline Elementen ((Document Outline (bookmarks)), Hinweisen (Annotations), oder Aktionen (Actions) verknüpft werden. In jedem Fall spezifiziert das Ziel die Sicht des Dokuments welche dargestellt werden soll wenn das Outline Element oder der Hinweis geöffnet, oder die Aktion durchgeführt werden soll. Zusätzlich kann eine optionale Dokument Öffnungs-Aktion spezifiziert werden.

### Unterstützte Zieltypen

Die folgenden Typen werden von der `Zend_Pdf` Komponente unterstützt.

#### Zend_Pdf_Destination_Zoom

Zeigt die spezifizierte Seite, mit den Koordinaten (Links, Oben) positioniert an der oberen-linken Ecke des Fensters und dem Inhalt der Seite vergrößert auf den Zoom Faktor.

Zielobjekte können durch Verwendung der `Zend_Pdf_Destination_Zoom::create($page, $left = null, $top = null, $zoom = null)` Methode erstellt werden.

Wobei:

- `$page` eine Zielseite ist (ein `Zend_Pdf_Page` Objekt oder eine Seitennummer).

- `$left` ist die linke Ecke der angezeigten Seite (float).

- `$top` ist eine obere Ecke der angezeigten Seite (float).

- `$zoom` ist ein Zoom Faktor (float).

`NULL`, wenn es für die `$left`, `$top` or `$zoom` Parameter spezifiziert wird, heißt "aktueller Wert der Viewer Anwendung".

Die `Zend_Pdf_Destination_Zoom` Klasse bietet die folgenden Methoden an:

- Float `getLeftEdge()`;

- `setLeftEdge(float $left)`;

- Float `getTopEdge()`;

- `setTopEdge(float $top)`;

- Float `getZoomFactor()`;

- `setZoomFactor(float $zoom)`;

#### Zend_Pdf_Destination_Fit

Zeigt die spezifizierte Seite an, wobei der Inhalt soweit vergrössert wird, dass er auf die komplette Seite passt sowohl Horizontal als auch Vertikal im Fenster. Wenn die benötigten horizontalen und vertikalen Vergrösserungsfaktoren unterschiedlich sind, wird der kleinere der zwei verwendet, und die Seite im Fenster mit der anderen Dimension zentriert.

Das Zielobjekt kann erstellt werden indem die `Zend_Pdf_Destination_Fit::create($page)` Methode verwendet wird.

Wobei `$page` eine Zielseite ist (ein `Zend_Pdf_Page` Objekt oder eine Seitennummer).

#### Zend_Pdf_Destination_FitHorizontally

Zeigt die spezifizierte Seite, mit den vertikalen Koordinaten an der oberen Ecke des Fensters positioniert, an und den Inhalt der Seite gerade genug vergrössert damit die komplette Breite der Seite in das Fenster passt.

Das Zielobjekt kann erstellt werden indem die `Zend_Pdf_Destination_FitHorizontally::create($page, $top)` Methode verwendet wird.

Wobei:

- `$page` ist eine Zielseite (ein `Zend_Pdf_Page` Objekt oder eine Seitenzahl).

- `$top` ist die obere Ecke der angezeigten Seite (float).

Die Klasse `Zend_Pdf_Destination_FitHorizontally` bietet auch die folgenden Methoden:

- Float `getTopEdge()`;

- `setTopEdge(float $top)`;

#### Zend_Pdf_Destination_FitVertically

Zeigt die spezifizierte Seite, mit den horizontalen Koordinaten an der oberen Ecke des Fensters positioniert, an und den Inhalt der Seite gerade genug vergrössert damit die komplette Höhe der Seite in das Fenster passt.

Das Zielobjekt kann erstellt werden indem die `Zend_Pdf_Destination_FitVertically::create($page, $left)` Methode verwendet wird.

Wobei:

- `$page` ist eine Zielseite (ein `Zend_Pdf_Page` Objekt oder eine Seitenzahl).

- `$left` die linke Ecke der angezeigten Seite ist. (float).

Die Klasse `Zend_Pdf_Destination_FitVertically` bietet auch die folgenden Methoden:

- Float `getLeftEdge()`;

- `setLeftEdge(float $left)`;

#### Zend_Pdf_Destination_FitRectangle

Zeigt die spezifizierte Seite an, wobei der Inhalt gerade genug vergrössert ist damit er komplett in das Rechteck passt das durch die Koordinaten links, unten, rechts und oben spezifiziert wird sowohl horizontal als auch vertikal. Wenn die notwendigen horizontalen und vertikalen Vergrösserungsfaktoren unterschiedlich sind, wird der kleinere der zwei verwendet, wobei das Rechteck im Fenster durch Verwendung der andern Dimension zentriert wird.

Das Zielobjekt kann erstellt werden indem die `Zend_Pdf_Destination_FitRectangle::create($page, $left, $bottom, $right, $top)` Methode verwendet wird.

Wobei:

- `$page` ist eine Zielseite (ein `Zend_Pdf_Page` Objekt oder eine Seitenzahl).

- `$left` die linke Ecke der angezeigten Seite ist. (float).

- `$bottom` die untere Ecke der angezeigten Seite ist (float).

- `$right` die rechte Ecke der angezeigten Seite ist (float).

- `$top` die obere Ecke der angezeigten Seite ist (float).

Die Klasse `Zend_Pdf_Destination_FitRectangle` bietet auch die folgenden Methoden an:

- Float `getLeftEdge()`;

- `setLeftEdge(float $left)`;

- Float `getBottomEdge()`;

- `setBottomEdge(float $bottom)`;

- Float `getRightEdge()`;

- `setRightEdge(float $right)`;

- Float `getTopEdge()`;

- `setTopEdge(float $top)`;

#### Zend_Pdf_Destination_FitBoundingBox

Zeigt die spezifizierte Seite an, wobei der Inhalt gerade genug vergrössert ist damit die Zeichenbox komplett in das Fenster passt, sowohl horizontal als auch vertikal. Wenn die notwendigen horizontalen und vertikalen Vergrösserungsfaktoren unterschiedlich sind, wird der kleinere der zwei verwendet, wobei die Zeichenbox im Fenster durch Verwendung der andern Dimension zentriert wird.

Das Zielobjekt kann erstellt werden indem die `Zend_Pdf_Destination_FitBoundingBox::create($page, $left, $bottom, $right, $top)` Methode verwendet wird.

Wobei `$page` eine Zielseite ist (ein `Zend_Pdf_Page` Objekt oder eine Seitenzahl).

#### Zend_Pdf_Destination_FitBoundingBoxHorizontally

Zeigt die spezifizierte Seite, mit den vertikalen Koordinaten an der oberen Ecke des Fensters positioniert, an und den Inhalt der Seite gerade genug vergrössert damit die komplette Breite der Zeichenbox in das Fenster passt.

Das Zielobjekt kann erstellt werden indem die `Zend_Pdf_Destination_FitBoundingBoxHorizontally::create($page, $top)` Methode verwendet wird.

Wobei

- `$page` eine Zielseite ist (ein `Zend_Pdf_Page` Objekt oder eine Seitenzahl).

- `$top` ist die obere Ecke der angezeigten Seite (float).

Die Klasse `Zend_Pdf_Destination_FitBoundingBoxHorizontally` bietet auch die folgenden Methoden:

- Float `getTopEdge()`;

- `setTopEdge(float $top)`;

#### Zend_Pdf_Destination_FitBoundingBoxVertically

Zeigt die spezifizierte Seite, mit den horizontalen Koordinaten an der oberen Ecke des Fensters positioniert, an und den Inhalt der Seite gerade genug vergrössert damit die komplette Höhe der Zeichenbox in das Fenster passt.

Das Zielobjekt kann erstellt werden indem die `Zend_Pdf_Destination_FitBoundingBoxVertically::create($page, $left)` Methode verwendet wird.

Wobei

- `$page` eine Zielseite ist (ein `Zend_Pdf_Page` Objekt oder eine Seitenzahl).

- `$left` ist die linke Ecke der angezeigten Seite (float).

Die Klasse `Zend_Pdf_Destination_FitBoundingBoxVertically` bietet auch die folgenden Methoden:

- Float `getLeftEdge()`;

- `setLeftEdge(float $left)`;

#### Zend_Pdf_Destination_Named

Alle oben aufgeführten Ziele sind "Explizite Ziele".

Zusätzlich dazu können PDF Dokumente ein Verzeichnis solcher Ziele enthalten welche verwendet werden können um nach ausserhalb des PDF's zu referenzieren (z.B. '`http://www.mycompany.com/document.pdf#chapter3`').

`Zend_Pdf_Destination_Named` Objekte erlauben es auf Ziele der benannten Zielverzeichnisse des Dokuments zu referenzieren.

Benannte Zielobjekte können erstellt werden indem man die `Zend_Pdf_Destination_Named::create(string $name)` Methode verwendet.

Die Klasse `Zend_Pdf_Destination_Named` bietet eine einzige zusätzliche Methode:

String `getName()`;

### Verarbeitung von Zielen auf Level des Dokuments

Die Klasse `Zend_Pdf` bietet ein Set von Methoden zur Verarbeitung von Zielen.

Jedes Zielobjekt (inklusive benannter Ziele) kann aufgelöst werden indem die Methode `resolveDestination($destination)` verwendet wird. Sie gibt ein passendes `Zend_Pdf_Page` Objekt zurück wenn das Zielobjekt gefunden wurde, andernfalls `NULL`.

Die Methode `Zend_Pdf::resolveDestination()` nimmt auch einen optionalen booleschen Parameter `$refreshPageCollectionHashes`, der standardmäßig true ist. Er zwingt das `Zend_Pdf` Objekt die Hashes der internen Kollektion der Seiten neu zu laden da die Liste der Seiten des Dokuments vom Benutzer aktualisiert sein könnte indem die Eigenschaft `Zend_Pdf::$pages` verwendet wird (Arbeiten mit Seiten). Das kann aus Gründen der Performance ausgeschaltet werden, wenn bekannt ist das die Liste der Seiten des Dokuments seit der letzten Anfragemethode nicht geändert wurde.

Die komplette Liste der benannten Ziele kann empfangen werden indem die Methode `Zend_Pdf::getNamedDestinations()` verwendet wird. Sie gibt ein Array von `Zend_Pdf_Target` Objekten zurück, welche entweder explizite Ziele oder eine GoTo Aktion sind (Aktionen).

Die Methode `Zend_Pdf::getNamedDestination(string $name)` gibt spezifizierte benannte Ziele zurück (ein explizites Ziel oder eine GoTo Aktion).

Das Verzeichnis der benannten Ziele des PDF Dokuments kann mit der Methode `Zend_Pdf::setNamedDestination(string $name, $destination)` aktualisiert werden, wobei `$destination` entweder ein explizites Ziel ist (jedes Ziel ausser `Zend_Pdf_Destination_Named`) oder eine GoTo Aktion.

Wenn `NULL` statt `$destination` spezifiziert ist, werden die spezifizierten benannten Ziele entfernt.

Benannte Ziele die nicht aufgelöst werden können, werden automatisch vom Dokument entfernt wenn das Dokument gespeichert wird.

#### Beispiel für die Verwendung von Zielen

    $pdf = new Zend_Pdf();
    $page1 = $pdf->newPage(Zend_Pdf_Page::SIZE_A4);
    $page2 = $pdf->newPage(Zend_Pdf_Page::SIZE_A4);
    $page3 = $pdf->newPage(Zend_Pdf_Page::SIZE_A4);
    // Erstellte Seiten, aber nicht in der Seitenliste enthalten

    $pdf->pages[] = $page1;
    $pdf->pages[] = $page2;

    $destination1 = Zend_Pdf_Destination_Fit::create($page2);
    $destination2 = Zend_Pdf_Destination_Fit::create($page3);

    // Gibt das $page2 Objekt zurück
    $page = $pdf->resolveDestination($destination1);

    // Gibt null zurück, die Seite 3 ist bis jetzt nicht im Dokument enthalten
    $page = $pdf->resolveDestination($destination2);

    $pdf->setNamedDestination('Page2', $destination1);
    $pdf->setNamedDestination('Page3', $destination2);

    // Gibt $destination2 zurück
    $destination = $pdf->getNamedDestination('Page3');

    // Gibt $destination1 zurück
    $pdf->resolveDestination(Zend_Pdf_Destination_Named::create('Page2'));

    // Gibt null zurück, die Seite 3 ist bis jetzt nicht im Dokument enthalten
    $pdf->resolveDestination(Zend_Pdf_Destination_Named::create('Page3'));

## Aktionen

Statt einfach zu einem Ziel im Dokument zu springen, kann ein Hinweis oder Outline Element eine Aktion für die Viewer Anwendung spezifizieren die auszuführen ist, wie das starten einer Anwendung, das Abspielen eines Sounds, oder der Änderung der Sichtweise des Hinweis Status.

### Unterstützte Typen von Aktionen

Die folgenden Typen von Aktionen werden beim Laden vom PDF Dokument erkannt:

- `Zend_Pdf_Action_GoTo` - geht zu einem Ziel im aktuellen Dokument.

- `Zend_Pdf_Action_GoToR` - geht zu einem Ziel in einem anderen Dokument.

- `Zend_Pdf_Action_GoToE` - geht zu einem Ziel in einem eingebetteten Dokument.

- `Zend_Pdf_Action_Launch` - startet eine Anwendung, öffnet oder druckt ein Dokument.

- `Zend_Pdf_Action_Thread` - beginnt einen Artikel Thread zu lesen.

- `Zend_Pdf_Action_URI` - löst ein URI auf.

- `Zend_Pdf_Action_Sound` - spielt einen Sound.

- `Zend_Pdf_Action_Movie` - spielt einen Film.

- `Zend_Pdf_Action_Hide` - versteckt oder zeigt einen oder mehrere Hinweise auf dem Bildschirm.

- `Zend_Pdf_Action_Named` - führt eine vordefinierte Aktion an der Viewer Anwendung aus:

  - NextPage - Geht zur nächsten Seite des Dokuments.

  - PrevPage - Geht zur vorhergehenden Seite des Dokuments.

  - FirstPage - Geht zur ersten Seite des Dokuments.

  - LastPage - Geht zur letzten Seite des Dokuments.

- `Zend_Pdf_Action_SubmitForm` - sendet Daten zu einem eindeutigen Ressourcenziel.

- `Zend_Pdf_Action_ResetForm` - setzt Felder mit Ihren Standardwerten.

- `Zend_Pdf_Action_ImportData` - importiert Feldwerte von einer Datei.

- `Zend_Pdf_Action_JavaScript` - führt ein JavaScript Skript aus.

- `Zend_Pdf_Action_SetOCGState` - setzt den Status von einem oder mehreren optionalen Inhaltsgruppen.

- `Zend_Pdf_Action_Rendition` - kontrolliert das Abspielen von Multimedia Inhalten (Beginnen, Stoppen, Pausieren oder Fortsetzen des Abspielens).

- `Zend_Pdf_Action_Trans` - Aktualisiert das Display eines Dokuments indem ein Übersetzungsverzeichnis verwendet wird.

- `Zend_Pdf_Action_GoTo3DView` - setzt die aktuelle Ansicht eines 3D Hinweises.

Nur `Zend_Pdf_Action_GoTo` Aktionen können aktuell von Benutzern erstellt werden. Das kann getan werden indem die Methode `Zend_Pdf_Action_GoTo::create($destination)` verwendet wird wobei `$destination` ein `Zend_Pdf_Destination` Objekt oder String ist der verwendet werden kann um ein benanntes Ziel zu identifizieren.

Es unterstützt auch die folgenden Methoden:

### Actions chaining

Actions objects can be chained using `Zend_Pdf_Action::$next` public property.

It's an array of `Zend_Pdf_Action` objects, which also may have their sub-actions.

`Zend_Pdf_Action` class supports RecursiveIterator interface, so child actions may be iterated recursively:

    $pdf = new Zend_Pdf();
    $page1 = $pdf->newPage(Zend_Pdf_Page::SIZE_A4);
    $page2 = $pdf->newPage(Zend_Pdf_Page::SIZE_A4);
    // Page created, but not included into pages list
    $page3 = $pdf->newPage(Zend_Pdf_Page::SIZE_A4);

    $pdf->pages[] = $page1;
    $pdf->pages[] = $page2;

    $action1 = Zend_Pdf_Action_GoTo::create(
                                Zend_Pdf_Destination_Fit::create($page2));
    $action2 = Zend_Pdf_Action_GoTo::create(
                                Zend_Pdf_Destination_Fit::create($page3));
    $action3 = Zend_Pdf_Action_GoTo::create(
                                Zend_Pdf_Destination_Named::create('Chapter1'));
    $action4 = Zend_Pdf_Action_GoTo::create(
                                Zend_Pdf_Destination_Named::create('Chapter5'));

    $action2->next[] = $action3;
    $action2->next[] = $action4;

    $action1->next[] = $action2;

    $actionsCount = 1; // Note! Iteration doesn't include top level action and
                       // walks through children only
    $iterator = new RecursiveIteratorIterator(
                                            $action1,
                                            RecursiveIteratorIterator::SELF_FIRST);
    foreach ($iterator as $chainedAction) {
        $actionsCount++;
    }
    printf("Actions in a tree: %d\n", $actionsCount++); // Prints 'Actions in a tree: 4'

### Document Open Action

Special open action may be specify a destination to be displayed or an action to be performed when the document is opened.

`Zend_Pdf_Target Zend_Pdf::getOpenAction()` method returns current document open action (or null if open action is not set).

`setOpenAction(Zend_Pdf_Target $openAction = null)` method sets document open action or clean it if `$openAction` is null.

## Document Outline (bookmarks)

A PDF document may optionally display a document outline on the screen, allowing the user to navigate interactively from one part of the document to another. The outline consists of a tree-structured hierarchy of outline items (sometimes called bookmarks), which serve as a visual table of contents to display the document’s structure to the user. The user can interactively open and close individual items by clicking them with the mouse. When an item is open, its immediate children in the hierarchy become visible on the screen; each child may in turn be open or closed, selectively revealing or hiding further parts of the hierarchy. When an item is closed, all of its descendants in the hierarchy are hidden. Clicking the text of any visible item activates the item, causing the viewer application to jump to a destination or trigger an action associated with the item.

`Zend_Pdf` class provides public property `$outlines` which is an array of `Zend_Pdf_Outline` objects.

    $pdf = Zend_Pdf::load($path);

    // Remove outline item
    unset($pdf->outlines[0]->childOutlines[1]);

    // Set Outline to be displayed in bold
    $pdf->outlines[0]->childOutlines[3]->setIsBold(true);

    // Add outline entry
    $pdf->outlines[0]->childOutlines[5]->childOutlines[] =
        Zend_Pdf_Outline::create('Chapter 2', 'chapter_2');

    $pdf->save($path, true);

Outline attributes may be retrieved or set using the following methods:

- `string getTitle()` - get outline item title.

- `setTitle(string $title)` - set outline item title.

- `boolean isOpen()` - true if outline is open by default.

- `setIsOpen(boolean $isOpen)` - set isOpen state.

- `boolean isItalic()` - true if outline item is displayed in italic.

- `setIsItalic(boolean $isItalic)` - set isItalic state.

- `boolean isBold()` - true if outline item is displayed in bold.

- `setIsBold(boolean $isBold)` - set isBold state.

- `Zend_Pdf_Color_Rgb getColor()` - get outline text color (null means black).

- `setColor(Zend_Pdf_Color_Rgb $color)` - set outline text color (null means black).

- `Zend_Pdf_Target getTarget()` - get outline target (action or explicit or named destination object).

- `setTarget(Zend_Pdf_Target|string $target)` - set outline target (action or destination). String may be used to identify named destination. Null means 'no target'.

- `array getOptions()` - get outline attributes as an array.

- `setOptions(array $options)` - set outline options. The following options are recognized: 'title', 'open', 'color', 'italic', 'bold', and 'target'.

New outline may be created in two ways:

- `Zend_Pdf_Outline::create(string $title[, Zend_Pdf_Target|string $target])`

- `Zend_Pdf_Outline::create(array $options)`

Each outline object may have child outline items listed in `Zend_Pdf_Outline::$childOutlines` public property. It's an array of `Zend_Pdf_Outline` objects, so outlines are organized in a tree.

`Zend_Pdf_Outline` class implements RecursiveArray interface, so child outlines may be recursively iterated using RecursiveIteratorIterator:

    $pdf = Zend_Pdf::load($path);

    foreach ($pdf->outlines as $documentRootOutlineEntry) {
        $iterator = new RecursiveIteratorIterator($documentRootOutlineEntry,
                                                  RecursiveIteratorIterator::SELF_FIRST);
        foreach ($iterator as $childOutlineItem) {
            $OutlineItemTarget = $childOutlineItem->getTarget();
            if ($OutlineItemTarget instanceof Zend_Pdf_Destination) {
                if ($pdf->resolveDestination($OutlineItemTarget) === null) {
                    // Mark Outline item with unresolvable destination using RED color
                    $childOutlineItem->setColor(new Zend_Pdf_Color_Rgb(1, 0, 0));
                }
            } else if ($OutlineItemTarget instanceof Zend_Pdf_Action_GoTo) {
                if ($pdf->resolveDestination($OutlineItemTarget->setDestination()) === null) {
                    // Mark Outline item with unresolvable destination using RED color
                    $childOutlineItem->setColor(new Zend_Pdf_Color_Rgb(1, 0, 0));
                }
            }
        }
    }

    $pdf->save($path, true);

All outline items with unresolved destinations (or destinations of GoTo actions) are updated while document saving by setting their targets to null. So document will not be corrupted by removing pages referenced by outlines.

## Annotations

An annotation associates an object such as a note, sound, or movie with a location on a page of a PDF document, or provides a way to interact with the user by means of the mouse and keyboard.

All annotations are represented by `Zend_Pdf_Annotation` abstract class.

Annotation may be attached to a page using `Zend_Pdf_Page::attachAnnotation(Zend_Pdf_Annotation $annotation)` method.

Three types of annotations may be created by user now:

- `Zend_Pdf_Annotation_Link::create($x1, $y1, $x2, $y2, $target)` where `$target` is an action object or a destination or string (which may be used in place of named destination object).

- `Zend_Pdf_Annotation_Text::create($x1, $y1, $x2, $y2, $text)`

- `Zend_Pdf_Annotation_FileAttachment::create($x1, $y1, $x2, $y2, $fileSpecification)`

A link annotation represents either a hypertext link to a destination elsewhere in the document or an action to be performed.

A text annotation represents a "sticky note" attached to a point in the PDF document.

A file attachment annotation contains a reference to a file.

The following methods are shared between all annotation types:

- `setLeft(float $left)`

- `float getLeft()`

- `setRight(float $right)`

- `float getRight()`

- `setTop(float $top)`

- `float getTop()`

- `setBottom(float $bottom)`

- `float getBottom()`

- `setText(string $text)`

- `string getText()`

Text annotation property is a text to be displayed for the annotation or, if this type of annotation does not display text, an alternate description of the annotation’s contents in human-readable form.

Link annotation objects also provide two additional methods:

- `setDestination(Zend_Pdf_Target|string $target)`

- `Zend_Pdf_Target getDestination()`