Kapitel 4. XFDF Annotationen

Die Annotation-Type Definitionen beschreiben Basistypen von Annotationen. Als Basistyp versteht man die grundlegende Definition einer bestimmten Art von Annotationen. Dieser Basistyp kann in weiterer Verwendung im Profil erweitert werden, um spezifizische Annotationstypen zu definieren, z.B. wird für die Pfeil-Annotation die Linien-Annotation als Basis verwendet. Im Folgenden wird ein Auszug des XFDF Annotionsprofils betrachtet.

<annotation-profile name="XFDF">          
<!-- ############################################################################### -->
<!-- ## Base types to match archetype definitions (used in reader class) -->
<!-- ############################################################################### -->

  <annotation-type name="Line" archetype="Line"
                   class="com.levigo.jadice.format.xfdf.annotation.XFDFLineAnnotation">
      <renderer toolkit="swing"
          class="com.levigo.jadice.format.xfdf.internal.renderer.XFDFLineAnnotationRenderer">
          ...
  	  </renderer>
  	
      <wrangler toolkit="swing"
         class="com.levigo.jadice.swing.internal.annotation.wranglers.xfdf.XFDFLineAnnotationWrangler">
         ...
      </wrangler>
      
      <interpreter class="com.levigo.jadice.format.xfdf.internal.semantics.XFDFLineAnnotationInterpreter"/>

	    <initializer class="com.levigo.jadice.format.xfdf.internal.XFDFAnnotationInitializer">
	       ...
      </initializer>
    
	    <customizer class="my.specific.xfdf.annotation.customizer.implementation.XFDFLineAnnotationCustomizer"/>

    	<fixed name="filled" propertyType="java.lang.Boolean">
		    ...
      </fixed>

      <fixed name="opacity" propertyType="java.lang.Float">
        ...
      </fixed>
  </annotation-type>
...
  <annotation-template name="XFDFLine" extends="Line">
    <labels>
      <label locale="en">Line</label>
      <label locale="de">Linie</label>
    </labels>
  </annotation-template>
...
</annotation-profile>

        

Wrangler-Klassen sind die Schnittstelle der Benutzungsoberfläche und dem Anwender. Sie dienen der Interaktion zwischen der GUI und dem Annotationsframework. Anwender können mit ihrer Hilfe Annotationen anlegen, verändern und editieren.

Im folgenden ist eine Übersicht der XFDF Wrangler-Klassen aufgezeigt. Diese Klassen sind zu finden in dem Package com.levigo.jadice.swing.internal.annotation.wranglers.xfdf des XFDF Format Moduls.

Für jede Annotationsklasse die in einer Annnotation-Typ Definition verwendet wird gibt es eine entsprechende Wrangler-Klasse. Der Wrangler-Klassenname setzt sich in der Regel aus den Namen der Annotationsklasse mit der Erweiterung 'Wrangler' am Ende zusammen, z.B. für die XFDFLineAnnotation lautet der Wrangler-Klassenname XFDFLineAnnotationWrangler.

Die Wrangler-Klassen haben aktuell keine XFDF formatspezifische Einstellungen. Die allgemeinen Einstellungen sind im Kapitel „Struktur und Aufbau von Annotation Profiles“ erläutert.

Falls bei der Weiterentwicklung Konfigurationsmöglichkeiten hinzukommen, wird dieser Abschnitt entsprechende aktualisiert.

XFDF Renderer-Klassen visualisieren die Definitionen / Eigenschaften von XFDF Annotationen. Ziel dieser Darstellung kann beispielsweise die Präsentation der Annotation auf der Benutzungsoberfläche oder während eines Druckprozesses sein. Allgemein kann man sagen, jede Form der visuellen Abbildung von XFDF Annotationen werden durch XFDF Renderer umgesetzt.

Die XFDF Annotationstypen besitzen jeweils spezifische Eigenschaften, die ausschließlich von dem zugehörigen XFDF Renderer dargestellt werden. Zur korrekten Darstellung von XFDF Annotationen ist es daher zwingend notwendig, dass zu jedem XFDF Annotationstyp der passende Renderer verwendet wird.

Die folgende Aufstellung gibt einen Überblick der zur Verfügung stehenden XFDF Renderer Klassen. Diese Klassen sind zu finden in dem Package com.levigo.jadice.format.xfdf.internal.renderer des XFDF Format Moduls.

Für jede Annotationsklasse die in einer Annnotation-Typ Definition verwendet wird gibt es eine entsprechende Renderer-Klasse. Der Renderer-Klassenname setzt sich in der Regel aus den Namen der Annotationsklasse mit der Erweiterung 'Renderer' am Ende zusammen, z.B. für die XFDFLineAnnotation lautet der Renderer-Klassenname XFDFLineAnnotationRenderer.

Die XFDF Renderer folgen durch das Format XFDF fest vorgegebenen spezifischen Vorgaben. Änderungen oder Anpassungen an den Renderen durch den Integrator sind daher nicht empfehlenswert. Die Klassen sind als Internal-API markiert, d.h. sie können im Profil verwendet werden, sind aber nicht zur Programmierung freigegeben.

Übersicht der Renderer-Klassen

Die Renderer-Klassen haben aktuell keine XFDF formatspezifische Einstellungen. Die allgemeinen Einstellungen sind im Kapitel „Struktur und Aufbau von Annotation Profiles“ erläutert.

Falls bei der Weiterentwicklung Konfigurationsmöglichkeiten hinzukommen, wird dieser Abschnitt entsprechende aktualisiert.

Acrobat bietet eine vielfältige Auswahl an Annotationstypen, die ein Anwender auf einem Dokument aufbringen kann. Vergleicht man diese Typen mit der im Abschnitt „Übersicht der XFDF Annotationsklassen“ vorgestellten XFDF Annotationsklassen, scheinen sich nicht alle Acrobat Annotationen direkt in XFDF Klassen widerzuspiegeln. Warum ist das so? Hat Acrobat ein eigenes Annotationsmodell? Die Antwort ist Nein. Acrobat nutzt die gleichen Typen von XFDF Annotationen wie sie auch durch die jadice documentplatform bereitgestellt werden. Doch wie kann Acrobat dann diese Vielfalt von Annotionen anbieten?

Das Geheimnis ist, XFDF Annotationstypen sind sehr vielfältig in ihren Möglichkeiten, ihres Erscheinungsbildes und ihres Verhaltens. Somit können aus einem XFDF Basistyp sehr viele unterschiedliche Annotationsarten konfiguriert und dem Anwender zur Nutzung angeboten werden.

Diese Abschnitt beschäftigt sich mit dem Thema, wie Acrobat spezifische Annotationen mit Hilfe der jadice documentplatform abgebildet werden.

Freundlicherweise hat das mitgelieferte jadice Default XFDF Profile die meisten Acrobat spezifischen Annotationen bereits vordefiniert. Für grundlegende Informationen zu dem XFDF Profile siehe auch Abschnitt „Annotation Profile für XFDF Annotationen“.

Abbildung 4.1. Darstellung der Acrobat Annotation Toolbar

In Abbildung 4.1, „Darstellung der Acrobat Annotation Toolbar“ ist die Annotation Toolbar des Acrobats zu sehen.

Die folgende Aufzählung beschreibt in der Reihenfolge der oben gezeigten Acrobat Annotation Toolbar die einzelnen Annotationstypen und gibt weitere Hinweise zu der korrespondierenden Deklarationen im XFDF Profile.

<annotation-template name="XFDFText" extends="Text">

<annotation-type name="Text" archetype="Text" 
  class="com.levigo.jadice.format.xfdf.annotation.XFDFTextAnnotation">

<annotation-template name="XFDFHighlight" extends="Highlight">

<annotation-type name="Highlight" archetype="Highlight" 
class="com.levigo.jadice.format.xfdf.annotation.XFDFHighlightAnnotation">

<annotation-template name="XFDFUnderline" extends="Underline">

<annotation-type name="Underline" archetype="Underline" 
class="com.levigo.jadice.format.xfdf.annotation.XFDFUnderlineAnnotation">

<annotation-template name="XFDFStrikeOut" extends="StrikeOut">

<annotation-type name="StrikeOut" archetype="StrikeOut"
class="com.levigo.jadice.format.xfdf.annotation.XFDFStrikeOutAnnotation">

<annotation-template name="XFDFCaretReplace" extends="Caret">

<annotation-type name="Caret" archetype="Caret"
    class="com.levigo.jadice.format.xfdf.annotation.XFDFCaretAnnotation">

<annotation-template name="XFDFCaret" extends="Caret">

<annotation-type name="Caret" archetype="Caret"
    class="com.levigo.jadice.format.xfdf.annotation.XFDFCaretAnnotation">

<annotation-template name="XFDFFreeTextTypeWriter" extends="FreeTextTypeWriter">

<annotation-type name="FreeTextTypeWriter" archetype="FreeTextTypeWriter"
class="com.levigo.jadice.format.xfdf.annotation.XFDFPlainFreeTextAnnotation">

<annotation-template name="XFDFFreeText" extends="FreeText">

<annotation-type name="FreeText" archetype="FreeText" extends="FreeTextTypeWriter"> und
<annotation-type name="FreeTextTypeWriter" archetype="FreeTextTypeWriter"
class="com.levigo.jadice.format.xfdf.annotation.XFDFPlainFreeTextAnnotation">

<annotation-template name="XFDFInk" extends="Ink">

<annotation-type name="Ink" archetype="Ink"
class="com.levigo.jadice.format.xfdf.annotation.XFDFInkAnnotation">

<annotation-template name="XFDFStamp" extends="Stamp">

<annotation-type name="Stamp" archetype="Stamp"
class="com.levigo.jadice.format.xfdf.annotation.XFDFStampAnnotation">

<annotation-template name="XFDFLine" extends="Line">

<annotation-type name="Line" archetype="Line"
class="com.levigo.jadice.format.xfdf.annotation.XFDFLineAnnotation">

<annotation-template name="XFDFLineArrow" extends="LineArrow">

<annotation-type name="LineArrow" archetype="LineArrow" extends="Line"> und
<annotation-type name="Line" archetype="Line"
class="com.levigo.jadice.format.xfdf.annotation.XFDFLineAnnotation">

<annotation-template name="XFDFSquare" extends="Square">

<annotation-type name="Square" archetype="Square"
class="com.levigo.jadice.format.xfdf.annotation.XFDFSquareAnnotation">

<annotation-template name="XFDFCircle" extends="Circle">

<annotation-type name="Circle" archetype="Circle" extends="Square"
class="com.levigo.jadice.format.xfdf.annotation.XFDFCircleAnnotation">

<annotation-template name="XFDFFreeTextCallout" extends="FreeTextCallout">

<annotation-type name="FreeTextCallout" archetype="FreeTextCallout" extends="FreeText">

<annotation-template name="XFDFPolygon" extends="Polygon">

<annotation-type name="Polygon" archetype="Polygon"
class="com.levigo.jadice.format.xfdf.annotation.XFDFPolygonAnnotation">

<annotation-template name="XFDFPolygonCloud" extends="PolygonCloud">

<annotation-type name="PolygonCloud" archetype="PolygonCloud"
class="com.levigo.jadice.format.xfdf.annotation.XFDFPolygonAnnotation">

<annotation-template name="XFDFPolyline" extends="Polyline">

<annotation-type name="Polyline" archetype="Polyline"
class="com.levigo.jadice.format.xfdf.annotation.XFDFPolylineAnnotation">

Selektionsbasierte Annotation brauchen für ihre Anwendbarkeit ein vorab ausgewählten, selektierten Text. Solche Annotationen sind XFDFHighlight, XFDFUnderline, XFDFStrikeOut, XFDFCaretReplace und XFDFCaret. Dieser Abschnitt befasst sich mit der Sicherstellung einer Text Selektion zum Aufbringen der genannten Annotationen.

Um diese Aufgabe zu erfüllen werden zwei Dinge benötigt, zum Einen ein TextSelectionTool zur Bereitstellung von selektierten Text, zum Anderen wird ein Command benötigt, das vor dem Aufbringen einer selektionsbasierenden Annotation eine Text Auswahl sicherstellt.

Weiterführende Informationen zum TextSelectionTool und Commands finden sich in den Abschnitten „Modus-Tools“ und „Kommandos (Command)“.

Das TextSelectionTool wird inital zum Start einer Anwendung im ToolManager registriert. Ein Beispiel findet sich hierzu in der Demoklasse BasicDemoApplication

ToolManager tm = ...; 
tm.register(TextSelectionTool.class, true);

Damit ist die erste Voraussetzung, ein TextSelectionTool zur Bereitstellung von selektierten Text, bereits gegeben. Im Weiteren wird ein Command benötigt, das vor dem Aufbringen einer selektionsbasierenden Annotation eine Text Auswahl sicherstellt.

Für jeden Typ von selektionsbasierenden Annotationen, wird ein entsprechendes Command benötigt. Allen dieser Commands liegt die Bereitstellung von selektierten Text zugrunde. Von daher macht es Sinn eine passende abstrakte Basisklasse zu anzulegen, die diese Prüfung übernimmt.

Codebeispiel einer abstrakten Command Basisklasse zum Anlegen einer textselektionsbasierten Annotation:

import static java.awt.geom.PathIterator.SEG_CLOSE;
import static java.awt.geom.PathIterator.SEG_LINETO;
import static java.awt.geom.PathIterator.SEG_MOVETO;

import java.awt.geom.GeneralPath;
import java.awt.geom.Path2D;
import java.awt.geom.PathIterator;
import java.util.ArrayList;
import java.util.List;
import java.util.UUID;

import org.jadice.util.log.Logger;
import org.jadice.util.log.LoggerFactory;

import com.levigo.jadice.annotation.Annotation;
import com.levigo.jadice.annotation.AnnotationPageSegment;
import com.levigo.jadice.annotation.Annotations;
import com.levigo.jadice.annotation.profiles.AnnotationProfile;
import com.levigo.jadice.document.Document;
import com.levigo.jadice.document.Selection;
import com.levigo.jadice.format.xfdf.annotation.XFDFAnnotation;
import com.levigo.jadice.swing.commands.AbstractDocumentCommand;
import com.levigo.jadice.swing.search.tool.TextSelectionTool;

public abstract class CreateTextSelectionBasedAnnotation extends AbstractDocumentCommand {

  private static final Logger LOGGER = LoggerFactory.getLogger(CreateTextSelectionBasedAnnotation.class);

  @Override
  protected void execute() {
    try {
      TextSelectionTool tool = getPageView().getToolManager().getTool(TextSelectionTool.class);

      List<Path2D> selections = new ArrayList<>();

      if (tool.getSelections().size() > 0) {
        for (Selection selection : tool.getSelections()) {
          final float[] tmp = new float[6];
          GeneralPath part = new GeneralPath();

          for (final PathIterator i = selection.getShape().getPathIterator(null); !i.isDone(); i.next()) {
            final int type = i.currentSegment(tmp);
            if (type == SEG_MOVETO) {
              part.moveTo(tmp[0], tmp[1]);
            }
            if (type == SEG_LINETO) {
              part.lineTo(tmp[0], tmp[1]);
            }
            if (type == SEG_CLOSE) {
              part.closePath();
              selections.add(new GeneralPath(part));
              part.reset();
            }
          }

          AnnotationPageSegment annotationPageSegment = Annotations.getAnnotationPageSegment(selection.getPage(), true);
          Annotation a = createAnnotation(selections);
          update(a);
          annotationPageSegment.addAnnotation(a);
        }

        tool.clearSelection();
      }
    } catch (Exception e) {
      LOGGER.error("Error creating annotation", e);
    }
  }

  protected abstract Annotation createAnnotation(List<Path2D> selections) throws Exception;

  protected abstract String getName();

  @Override
  protected boolean canExecute() {
    return getPageView() != null && getPageView().getDocument() != null && getPageView().getToolManager() != null
        && getPageView().getToolManager().getTool(TextSelectionTool.class) != null
        && getPageView().getToolManager().getTool(TextSelectionTool.class).getSelections().size() > 0;
  }

  protected AnnotationProfile getProfile(Document document) {
    AnnotationProfile profile = (AnnotationProfile) document.getProperties().get(AnnotationProfile.class.getName());
    if (profile == null) {
      profile = AnnotationProfile.getDefaultProfile();
    }
    return profile;
  }

  public void update(Annotation a) {
    updateTitle(a);
    updateID(a);
  }

  public void updateTitle(Annotation a) {
    if (a instanceof XFDFAnnotation) {
      final XFDFAnnotation xfdf = ((XFDFAnnotation) a);
      if (xfdf.getTitle() == null) {
        // Set user name -> Adobe-Reader behavior
        final String title = System.getProperty("user.name");
        xfdf.setTitle(title);
      }
    }
  }

  public void updateID(Annotation a) {
    if (a.getID() == null) {
      UUID id = UUID.randomUUID();
      a.setID(id.toString());
    }
  }
}

Die obige Klasse prüft das Vorhandensein von selektierten Text und bestimmt über den Rückgabewert der canExecute-Methode den Enabled-State des Command der Annotation.

Codebeispiel zum Anlegen einer Markierungsannotation:

import java.awt.geom.Path2D;
import java.util.List;

import com.levigo.jadice.annotation.Annotation;
import com.levigo.jadice.annotation.profiles.AnnotationProfile;
import com.levigo.jadice.format.xfdf.annotation.XFDFTextMarkupAnnotation;

public class CreateTextHighlightAnnotation extends CreateTextSelectionBasedAnnotation {

  @Override
  protected Annotation createAnnotation(List<Path2D> selections) throws Exception {
    AnnotationProfile profile = getProfile(getPageView().getDocument());
    XFDFTextMarkupAnnotation a = (XFDFTextMarkupAnnotation) profile.getTemplate(getName()).createNewInstance();
    a.setCoords(selections);
    return a;
  }
  
  @Override
  protected String getName() {
    return "XFDFHighlight";
  }
}                        

Codebeispiel zum Anlegen einer durchgestrichenen Caret-Annotation:

import java.awt.geom.Path2D;
import java.awt.geom.Rectangle2D;
import java.util.List;

import com.levigo.jadice.annotation.Annotation;
import com.levigo.jadice.annotation.profiles.AnnotationProfile;
import com.levigo.jadice.format.xfdf.annotation.XFDFCaretAnnotation;
import com.levigo.jadice.format.xfdf.annotation.XFDFStrikeOutAnnotation;

public class CreateCaretAnnotation extends CreateTextSelectionBasedAnnotation {

  @Override
  protected Annotation createAnnotation(List<Path2D> selections) throws Exception {
    AnnotationProfile profile = getProfile(getPageView().getDocument());
    XFDFCaretAnnotation caret = (XFDFCaretAnnotation) profile.getTemplate(getName()).createNewInstance();
    if ("Replace".equals(caret.getIntent())) {
      XFDFStrikeOutAnnotation strikeOut = (XFDFStrikeOutAnnotation) profile.getTemplate(
          getName()).createNewInstance();
      strikeOut.getCoords().addAll(selections);
      strikeOut.setStrokeColor(caret.getStrokeColor());
      caret.setStrikeOut(strikeOut);
    }
    Rectangle2D selection = selections.get(selections.size() - 1).getBounds2D();
    double h = selection.getHeight() * (2d / 3d);
    double w = h * 1.27d; // ratio width / height taken from AdobeReader created caret anno
    double x = selection.getX() + selection.getWidth() - (w / 2d);
    double y = selection.getY() + (selection.getHeight() * (1d / 3d));
    caret.setLocation(x, y);
    caret.setSize(w, h);
    return caret;
  }
  
  @Override
  protected String getName() {
    return "XFDFStrikeOutTextEdit";
  }
}

Acrobat bietet zwei verschiedene Sets "Dynamisch" und "Geschäftlich" von vordefinierten Stempeln an. Diese kann man ähnlich konfigurieren oder auch eigene Stempel Typen anlegen. Im Folgenden wird ein "Hier unterschreiben"- Stempel examparisch beschrieben.

Für die Verwendung von vordefinierten Stempeln muss im ersten Schritt ein entsprechendes Template angelegt werden. Das in der Tabelle Tabelle 4.1, „Übersicht der Acrobat Annotationen in Zuordnung der Dekalration im XFDF Annotation Profile“ genannte Stamp Annotation Template dient dabei als zu erweiternde Basis für die Spezifikation spezifischer Stempel.

          
<!-- Template to define customizer -->
<annotation-template name="XFDFCustomStamp" extends="XFDFStamp">
  <customizer class="com.levigo.jadice.format.xfdf.annotation.customizer.XFDFStampAnnotationCustomizer" />
</annotation-template>

          

Im obigen Beispiel wird ein XFDFCustomStamp als Standard Template für alle zu definierenden Stempel erzeugt. Die Klasse XFDFStampAnnotationCustomizer dient dabei als Customizer für die zu erzeugenden Stempel. Customize können als Beispiel ein gewünschtes Icon oder auch Appearance setzen.

Im nächsten Schritt wird der "Hier unterschreiben"-Stempel konfiguriert.

          
<annotation-template name="XFDFStampSHSignHere" extends="XFDFCustomStamp">
  <labels>
  <label locale="en">Sign here</label>
  <label locale="de">Hier unterschreiben</label>
  </labels>
  <default name="icon">SHSignHere</default>
</annotation-template>

Die Labels bestimmen den Anzeigename bzw. den Tooltip der Annotation. Die Konfiguration erlaubt die Angabe Locale spezifischer Labels. Weiterhin wird eine passende Icon Resource mit dem Namen "SHSignHere" benannt. Icon Resource NAmen sollten dabei eindeutig gewählt werden. Es ist Aufgabe des Customizers das passende Icon für die angebende Icon Resource der Stamp Annotation zur Verfügung zu stellen.

Die XFDFRubberTool Klasse ist eine Tool Implementierung mit der man Elemente der XFDF Ink-Annotation löschen / entfernen kann.

Um das Rubber-Tool verwenden zu können muss es bei der ToolManager Klasse registriert werden:

ToolManager tm = ...; 
tm.register(XFDFRubberTool.class, true);