Kapitel 5. Klassen- und Funktionsüberblick

Modus-Tools dienen dazu, dem Benutzer verschiedene Arten der Interaktion mit jadice anzubieten. Wird eines dieser Tools genutzt, so können die anderen nicht gleichzeitig verwendet werden. Die folgenden Modus-Tools stellt die jadice document platform zur Verfügung:

Zusätzlich zur bereits beschriebenen Selektion von Text über das TextSelectionTool besteht die Möglichkeit, rechteckige Bereiche einer Seite zu markieren – unabhängig davon ob sich Text an dieser Position befindet oder nicht. Diese Funktionalität wird durch das AreaSelectionTool angeboten. Das Tool ist kein Modus-Tool, sondern nach Registrierung im Hintergrund aktiv.

Um das AreaSelectionTool zu verwenden, müssen zwei Bedingungen erfüllt sein:

Bereiche, die durch das AreaSelectionTool markiert wurden, werden als eingefärbter Rahmen über den Seiteninhalten angezeigt. Dieser kann nachträglich noch verschoben oder in seiner Größe geändert werden. Zusätzlich bietet das Tool für selektierte Bereiche die folgenden drei Aktionen an:

Ein zentrales Tool, das nach der Registrierung am ToolManager im Hintergrund seine Arbeit verrichtet, ist das PopupMenuTool. Es stellt einen Weg zur Verfügung um Kontextmenüs auf einer ViewComponent anzubieten. Die Einträge dieser Menüs werden von Instanzen des Typs MenuContributor beigesteuert. Im Besonderen implementiert die Basisklasse Tool das Interface MenuContributor. Jedes Tool kann somit dem Kontextmenü Einträge hinzufügen.

Das PopupMenuTool reagiert auf Klicks der rechten Maustaste und stellt daraufhin das Kontextmenü an der Mausposition dar.

Da das PopupMenuTool kein Modus-Tool ist, kann es gleichzeitig mit anderen Tools (und im Besonderen mit einem Modus-Tool) verwendet werden. Zu beachten ist dabei, dass höher priorisierte Tools – wozu insbesondere die Modus-Tools gehören – das Rechtsklick-Event konsumieren können. In diesem Fall kommt es nicht zur Anzeige des Kontextmenüs. Ein Beispiel für dieses Verhalten ist das HoverLensTool, das über die rechte Maustaste seinen Zoomfaktor verringert.

Über das KeyBindingsTool steht Integratoren eine einfache und komfortable Möglichkeit zur Verfügung, Tastaturbefehle zu definieren, die an eine ViewComponent gebunden sind. Hat diese den Fokus, so werden Tastaturbefehle an das KeyBindingsTool weitergeleitet. Wurde für einen gegebenen Tastaturbefehl eine Action hinterlegt, wird diese ausgeführt.

Während Tastaturbefehle auch mit regulären Swing-Mitteln definiert werden können, bietet der Ansatz über ein Tool den Vorteil, dass die Möglichkeiten der Tool-API zum Tragen kommen. Im Besonderen kann die Reihenfolge (und somit die Priorisierung) der Tools angepasst werden. Dadurch kann vermieden werden, dass ein Tastaturbefehl durch ein anderes Tool konsumiert wird und deshalb nie zur Ausführung gelangt.

Das EmbeddedLinkTool ist ein zentrales Tool zur Verteilung von Instruktionen (Instructions), die beispielsweise aus Sprungzielen in Dokumenten entstanden sind. Ist das EmbeddedLinkTool im ToolManager registriert verteilt es Instruktionen an die ihm bekannten InstructionExecutor-Implementierungen. Verlinkungen innerhalb eines Dokuments können mit dem mitgelieferten PortfolioInstructionExecutor behandelt werden. Für Verlinkungen auf URIs ist der URIExecutor als Demo-Implementierung beigefügt. In Kapitel „Instructions und Executors“ findet sich eine ausführliche Erklärung zur Funktionsweise von Instructions

Verschiedene Tools erfüllen den Zweck, als Reaktion auf Benutzereingaben durch das angezeigte Dokument zu navigieren. Es können dabei sowohl Keyboard- als auch Maus-Ereignisse verarbeitet werden. Im Einzelnen handelt es sich um die folgenden Tools:

Das CrossHairTool rendert über den Seiteninhalten ein Fadenkreuz an der aktuellen Mausposition, das dem Nutzer als Orientierungshilfe dient. Es kann mit anderen Tools kombiniert werden.

Bietet die Möglichkeit, eine Thumbnail Ansicht (ThumbnailView, siehe „Anzeige von Dokumenten“) über den eigentlichen Dokumentinhalten einzublenden. Die Seitenminiaturen werden auf einer halbtransparenten Fläche dargestellt und blenden sich nach kurzer Zeit automatisch wieder aus. Über einen entsprechenden Button können sie auf dauerhafte Anzeige geschaltet werden.

Das PDF-Format bietet die Möglichkeit Dokumente zu verschlüsseln und für deren Anzeige ein Passwort zu fordern.^[42] Die Klasse PDFPasswordProviderTool bietet eine grafische Oberfläche zur Eingabe des Passworts durch den Anwender. Das Tool bleibt zunächst im Hintergrund und nimmt lediglich dann seine Arbeit auf, wenn ein Dokument gelesen wird, für dessen Anzeige ein Passwort notwendig ist.

Die Verwaltung der Zustände aller Tools obliegt dem ToolManager. Da jedes Tool aber seinen ToolManager kennt, kann es auch selbst Zustandswechsel auslösen. Für die einzelnen Zustände sieht das Zusammenspiel der beiden Klassen folgendermaßen aus:

Tools werden mit Eingabeereignissen versorgt, die auf der ViewComponent auftreten, der sie über den ToolManager zugeordnet sind. Die abstrakte Klasse Tool bietet verschiedene Methoden an, die selektiv überschrieben werden können um auf bestimmte Ereignisse, wie beispielsweise Mausbewegungen oder Klicks, zu reagieren.

Zur Weitergabe der Ereignisse wird die aus AWT/Swing bekannte Klassenhierarchie genutzt, aber zusätzlich um jadice-spezifische Informationen angereichert. Jedes Event, das einem Tool mitgeteilt wird, entspricht der abstrakten Klasse EditEvent, die wiederum von java.util.EventObject erbt. Es gibt drei Arten von Event, die einem Tool in Form von konkreten Ausprägungen des EditEvent mitgeteilt werden:

Jedes EditEvent bietet über die Methode EditEvent.getInputEvent() Zugriff auf das ursprüngliche java.awt.event.InputEvent, auf dessen Basis es erzeugt wurde.

Damit Tools ihre Arbeit ausführen können, sind oft weitere Kontextinformationen notwendig, die über das, was ein reguläres java.awt.event.InputEvent bietet, hinausgehen. Das EditEvent liefert daher zusätzliche Angaben wie beispielsweise die GUI-Komponente, auf der das Event auftrat, die angezeigte Seite, oder die geltenden RenderControls.^[43]

EditEvents beziehen sich oft auf eine Page, zum Beispiel dann, wenn sich der Mauszeiger in der Nähe oder über der Darstellung einer Seite befindet. Allerdings können die Ereignisse auch ohne Seitenkontext auftreten, weshalb Tools mit diesem Umstand umgehen können müssen.

Insbesondere das MouseEditEvent bietet verschiedene Methoden, die ein komfortables Arbeiten mit Events in Seitenkontexten ermöglichen. Es existieren zum Beispiel unterschiedliche Wege, die aktuellen Mauskoordinaten herauszufinden. Welche Methode in einer bestimmten Situation geeignet ist, hängt davon ab, was erreicht werden soll.

Da bei einem ToolManager im Regelfall mehrere Tools registriert sind, ist es wichtig, die Reihenfolge, in der die verschiedenen Tools mit Ereignissen versorgt werden, beeinflussen zu können. Eine Tool-Implementation kann weitgehend selbst steuern, wie früh oder spät in der Reihenfolge sie mit Ereignissen bedacht werden soll. Die Methode Tool.getDispatchPriority() muss hierzu einen Wert zwischen Tool.MIN_PRIORITY und Tool.MAX_PRIORITY zurückgeben. Je näher an MAX_PRIORITY der Wert ist, desto früher wird das Tool mit Ereignissen versorgt.

Hat ein Tool ein Ereignis erhalten und hat es sich dafür entschieden, darauf zu reagieren, ist es oft sinnvoll dafür zu sorgen, dass keine anderen Tools mehr auf das Ereignis reagieren. Hierzu genügt es, beim Verarbeiten des Ereignisses dessen consume()-Methode aufzurufen. Sobald ein Ereignis konsumiert wurde, wird es nicht mehr an weitere Tools zur Verarbeitung übergeben. Im Umkehrschluss bedeutet dies auch, dass Tools nicht explizit prüfen müssen, ob ein Ereignis bereits konsumiert wurde, da sie dieses sonst überhaupt nicht erhalten hätten.

Nachdem eine ViewComponent ihre Seitendarstellung gerendert hat, erhalten registrierte und eingeschaltete Tools die Gelegenheit, eigene visuelle Elemente beizutragen. Für jede sichtbare Seite wird zu diesem Zweck die Methode Tool.render(RenderParameters parameters, boolean isActive) aufgerufen. Neben dem booleschen Parameter isActive, der darüber informiert ob das angefragte Tool zur Zeit aktiv ist, werden über die Instanz von RenderParameters weitere Kontextinformationen übermittelt. Diese beinhalten neben dem Zielgrafikkontext (als Instanz von java.awt.Graphics2D) die aktuelle Seite, der Bereich in den die Seite gerendert wurde, die geltenden RenderControls und weitere Angaben.

Wie es eine Dispatch-Reihenfolge für die Verteilung von Ereignissen gibt, existiert eine separate Reihenfolge für die Zeichenvorgänge. Die Anordnung wird durch Prioritätswerte bestimmt, die von den einzelnen Tools erfragt werden über einen Aufruf von Tool.getRenderPriority(). Die zurückgelieferten Werte müssen zwischen Tool.MIN_PRIORITY und Tool.MAX_PRIORITY liegen. Die Standardimplementierung gibt den Wert Tool.DEFAULT_PRIORITY zurück, der ein Mittelwert der beiden Extrema ist.

In der Regel sollten die Dispatch- und Renderreihenfolge in einer inversen Beziehung zueinander stehen. Tools können konzeptionell wie ein Stapel von Ebenen betrachtet werden: je weiter oben auf dem Stapel ein Tool liegt, desto früher werden Ereignisse verteilt und desto später wird gerendert.

Da jedes Tool gleichzeitig Instanz von MenuContributor ist, kann es Elemente zu einer Menü- oder Symbolleistenstruktur beitragen. Dies funktioniert nach dem unter „Menüs und Symbolleisten“ erläuterten Prinzip. Wofür die aus diesen Beträgen entstehenden Strukturen verwendet werden ist zunächst nicht eingeschränkt. Im Besonderen können sie jedoch durch Einbinden des PopupMenuTools als Kontextmenü über der ViewComponent verfügbar gemacht werden.

Unter „Implementation von Tools“ finden sich Beispiele für die Arbeit mit der Klasse Tool.