Tools

In „Anzeige von Dokumenten“ wird beschrieben, welche Möglichkeiten die jadice document platform zur Anzeige von Dokumenten bietet. Im Regelfall gehen die Anforderungen jedoch über eine einfache, statische Anzeige hinaus. So besteht oftmals der Wunsch, Werkzeuge anzubieten, die mit den dargestellten Seiten interagieren, also zum Beispiel Textselektion oder die Wahl des Zoom-Faktors anbieten. In anderen Fällen sollen ergänzende Informationen zum Dokument nicht nur irgendwo in der Programmoberfläche, sondern direkt über der Seite eingeblendet werden. Komponenten, die solche Anforderungen realisieren, werden in jadice Tools genannt. Die Tool-API bietet einen flexiblen Einsprungspunkt zur Konfiguration und Erweiterung der bestehenden Möglichkeiten.

Überblick zur Funktionsweise

Die Implementation eigener Tools erfolgt durch Erben von der der Klasse Tool. Jedes Tool erhält die Möglichkeit Eingabeereignisse zu verarbeiten, Informationen oberhalb des dargestellten Dokuments zu rendern, sowie Einträge für das Kontextmenü beizusteuern. Manche Tools nehmen diese Aufgaben wahr um für den Nutzer einen Modus zur Interaktion mit jadice anzubieten. Sie schließen daher die gleichzeitige Aktivät eines anderen Modus-Tools aus. Andere Tools bilden keinen Modus, sondern stellen lediglich Zusatzfunktionalität, wie beispielsweise einen Eintrag ins Kontextmenü, zur Verfügung.

Für eine Instanz von ViewComponent[38] können mehrere Tools registriert sein. Die Verwaltung aller registrierten Tools erfolgt nicht durch die ViewComponent selbst, sondern durch einen ihr zugeordneten ToolManager. Dieser legt fest, welche Tools zu einem gegebenen Zeitpunkt ihre Arbeit ausführen dürfen. Das Umschalten zwischen verschiedenen Modus-Tools wird somit auch über den ToolManager geregelt. Nähere Details zum ToolManager gibt „Der ToolManager.

Mitgelieferte Tools

Im Lieferumfang der jadice document platform sind mehrere häufig benötigte Tools enthalten. In vielen Fällen reicht deren Funktionsumfang aus um die Anforderungen einer jadice-Integration zu erfüllen. In diesem Fall ist es lediglich notwendig, die vorhandenen Tools zu konfigurieren. Sie stehen daraufhin zur Verwendung bereit. Im Folgenden wird kurz auf die Funktionen der relevanten mitgelieferten Tools eingegangen.

Modus-Tools

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:

PanTool

Das Modus-Tool, das in der jadice Demo-Applikation per Default aktiv ist. Es bietet die Möglichkeit, den angezeigten Seitenbereich mit der Maus zu verschieben (»panning«). Während des Verschiebens wird eine Hand als Mauszeiger verwendet.

AnnotationTool

Stellt einen Modus zur Verfügung, der die Bearbeitung von Annotationen zulässt. Dies beinhaltet beispielsweise das Verschieben von Annotation auf der Seite oder, bei entsprechenden Annotationstypen, das Ändern ihrer Größe.

HoverLensTool

Modus-Tool, das eine schwebende Lupe über dem Dokumentinhalt anzeigt. Es werden sowohl der eigentliche Dokumentinhalt, als auch darauf angebrachte Annotationen vergrößert. Durch Drücken der linken Maustaste wird der Vergrößerungsfaktor der Lupe erhöht; mittels rechter Maustaste wird er verringert.

TextSelectionTool

Bietet einen Modus an, der es zulässt, Text zu markieren. Dies ist ausschließlich für Dokumente mit Textinhalten möglich. Der markierte Text kann in die Zwischenablage kopiert oder per Drag&Drop[39] in ein anderes Programm übernommen werden.

Selektion von Seitenbereichen

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:

  • Es muss ein Activation Modifier auf dem Tool gesetzt sein. Dieser bestimmt die Tasten-/Mauskombination die der Nutzer verwenden muss um das Tool zu bedienen. Per Default wird eine Area Selection bei gedrückter Shift-Taste durch Ziehen mit der linken Maustaste durchgeführt.

  • Die Tasten-/Mauskombination darf nicht durch ein höher priorisiertes Tool (oder eine andere Komponente) abgefangen und konsumiert werden. Dies kann zum Beispiel dann vorkommen, wenn das Modus Tool ›Schwebende Lupe‹ (HoverLensTool) aktiv ist. Wird die Schwebende Lupe verwendet, kann somit keine Area Selection ausgeführt werden.

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:

  • Zoom der Seitendarstellung auf den gewählten Bereich

  • Kopieren der Dokumentinhalte des selektierten Bereichs in die Zwischenablage als Bilddaten

  • Kopieren der Textinhalte des selektierten Bereichs in die Zwischenablage. Neben dem Kopieren über entsprechende Aktionen kann der ausgewählte Text auch per Drag&Drop[40] in ein anderes Programm übernommen werden.

Kontextmenüs auf einer ViewComponent

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.

Binden von Tastaturbefehlen über ein Tool

Ü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.

Verarbeiten von Verlinkungen und PDF-Actions mit dem EmbeddedLinkTool

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

Navigations-Tools

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:

KeyboardNavigationTool

Die Darstellung von Seiten durch eine PageView erfolgt normalerweise innerhalb einer JScrollPane. Durch die Swing Standard Bindings reagiert diese wenn die Pfeiltasten auf der Tastatur betätigt werden und verändert daraufhin den angezeigten Seitenbereich (»panning«). Wird zur Darstellung ein Seitenlayout[41] verwendet, das Seiten fortlaufend anzeigt, kann über diesen Mechanismus auf andere Seiten gewechselt werden. Um auch in anderen Seitenlayouts den Wechsel zu vorhergehenden oder nachfolgenden Seiten zu ermöglichen, existiert das KeyboardNavigationTool. Es reagiert ausschließlich dann, wenn der angezeigte Bereich am Rand einer Seite liegt und in entsprechender Richtung eine weitere Seite existiert. Sind diese Kriterien erfüllt, so erfolgt bei Tastendruck ein Wechsel auf die angrenzende Seite. Befindet sich beispielsweise die Anzeige am unteren Seitenrand und es wird die -Taste gedrückt, so wird anschließend die nachfolgende Seite am oberen Seitenrand angezeigt.

MouseWheelTool

Reagiert auf Bewegungen des Mausrads und verändert daraufhin den angezeigten Seitenbereich (»panning«).

MouseWheelZoomTool

Reagiert auf Bewegungen des Mausrads sofern ein zusätzlicher Modifier gedrückt wird. Per Default handelt es sich dabei um die Strg-Taste. Als Reaktion auf die Eingabe wird der Zoomfaktor zur Darstellung der Seiteninhalte verändert.

MouseGestureTool

Dient der Navigation im Dokument durch Mausbewegungen bei gedrückter linker Maustaste.

Das Tool liegt der Auslieferung als Demo-Klasse im Quelltext bei und kann somit für Integrationen angepasst oder als Beispiel für andere Tool-Implementierungen verwendet werden.

GalleryNavigationTool

Erlaubt die Navigation im Dokument mittels zweier Schaltflächen, die am linken beziehungsweise rechten Rand des dargestellten Seitenbereiches eingeblendet werden. Die Einblendung erfolgt automatisch wenn sich der Mauszeiger in der Nähe ihrer Position befindet.

Fadenkreuz als Mauszeiger

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.

Thumbnail-Ansicht als Tool

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.

Passworteingabe mittels Tool

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.

Zustände von Tools

Um die Steuerung der Benutzeroberfläche mittels Tools zu ermöglichen, können diese sich in unterschiedlichen Zuständen befinden. Dies erlaubt angepasste Reaktionen abhängig vom jeweiligen Zustand. Im Einzelnen handelt es sich dabei um die folgenden Zustände:

registriert

Jedes Tool kann bei genau einem ToolManager registriert sein. Nur registrierte Tools werden mit Ereignissen versorgt und können am Rendering Teilnehmen. Ohne Registrierung können Tools keiner ViewComponent zugeordnet werden und nichts zur grafischen Darstellung beitragen.

eingeschaltet

Nicht jedes registrierte Tool steuert automatisch seine Funktionalität bei. Stattdessen werden nur jene Tools um ihren Beitrag gebeten, die auch eingeschaltet sind. Bereits bei der Registrierung eines Tools kann angegeben werden, ob es initial ein- oder ausgeschaltet sein soll.

aktiv

In manchen Situationen kann es notwendig sein, dass ein Tool, obwohl es in der Dispatch-Reihenfolge eigentlich nicht an erster Stelle steht, temporär vorrangig vor allen anderen Tools die Gelegenheit zur Verabeitung von Ereignissen erhält. Diese Funktionalität ist insbesondere wichtig um die weiter oben beschriebenen Modus-Tools (siehe „Modus-Tools“) zu realisieren. Ein temporär vorrangig behandeltes Tool wird als aktives Tool bezeichnet und kann dem Nutzer als Modus präsentiert werden. Zu jedem Zeitpunkt kann maximal ein Tool als aktiv gesetzt sein. Die Aktivierung eines Tools führt somit gegebenenfalls zur Deaktivierung des bisher aktiven Tools. Die Aktivierung eines Tools verändert ausschließlich die ›Dispatch Priority‹. Die ›Render Priority‹ wird durch diese temporäre Änderung nicht beeinflusst.

exklusiv

Es kann sinnvoll sein, bestimmten Tools für einen begrenzten Zeitraum die alleinige Kontrolle zu überlassen, um Konflikte mit anderen Tools während komplexer Operationen zu vermeiden. Diese Exklusivität greift zum Beispiel bei der Annotationsbearbeitung, während Annotationen in der Größe verändert oder verschoben werden, sowie während der Texteditor aktiv ist. Der Exklusivmodus sorgt dafür, dass ausschließlich das exklusive Tool mit Ereignissen versorgt wird und Gelegenheit zum Rendering erhält.

Der ToolManager hat die Aufgabe, Tools für eine ViewComponent zu verwalten. Aus diesem Grund hat jede ViewComponent genau einen ToolManager, und jeder ToolManager gehört zu genau einer ViewComponent. Er kann erfragt werden über den Aufruf ViewComponent.getToolManager(). Der ToolManager versorgt die bei ihm registrierten Tools mit Ereignissen und gibt ihnen die Gelegenheit, zum Rendering beizutragen.

Um zu bestimmen, in welcher Reihenfolge die einzelnen Tools mit Ereignissen versorgt werden, trägt jedes Tool eine ›Dispatch Priority‹. Der ToolManager liest deren Wert aus, bringt die registrierten Tools in eine entsprechende Reihenfolge und versorgt sie in dieser Anordnung mit Ereignissen. Zusätzlich existiert für jedes Tool ein weiterer unabhängiger Prioritätswert, die ›Render Priority‹. Über diesen Wert wird bestimmt, in welcher Reihenfolge die Tools Gelegenheit bekommen, zum Rendering-Vorgang beizutragen. Beide Prioritätswerte werden durch die einzelnen Tools definiert und vom ToolManager in ihre Reihenfolge gebracht.

Die Verwaltung aller registrierten Tools erfolgt auf Basis der Tool-Zustände. Für jedes Tool kann dessen Zustand durch Methodenaufrufe auf dem ToolManager geändert werden. Dies erlaubt beispielsweise eine manuelle Änderung des Aktivitäts-Zustands durch den Nutzer über entsprechende Commands. Somit wird das explizite Umschalten zwischen mehreren Modus-Tools realisiert. Im Einzelnen werden die Zustände wie folgt gesteuert:

registriert

Die Registrierung eines Tools erfolgt mittels ToolManager.register(Class<T> toolClass, boolean enabled). Es wird dabei lediglich der Klassenname eines Tools angegeben. Die zu registrierende Instanz wird durch den ToolManager automatisch erzeugt. Zusätzlich wird bei diesem Aufruf angegeben, ob das neu registrierte Tool initial eingeschaltet sein soll oder nicht.

eingeschaltet

Ob ein Tool eingeschaltet sein soll oder nicht kann gesteuert werden, indem der Methode ToolManager.setEnabled(Class<? extends Tool> toolClass, boolean enabled) der Wert true (eingeschaltet) oder false (ausgeschaltet) übergeben wird.

aktiv

Um ein Tool als aktiv zu ernennen, wird dessen Klasse an die Methode ToolManager.activate(Class<? extends Tool> toolClass) übergeben. Neben dieser manuellen Art der Aktivierung, besteht die Möglichkeit das aktive Tool automatisiert zu ernennen. Details dazu gibt „Automatische Steuerung der Tool-Aktivierung“.

exklusiv

Um ein Tool als exklusiv zu bestimmen, wird dessen Klasse an die Methode ToolManager.setExclusive(Class<? extends Tool> toolClass) übergeben. Es ist wichtig, sicherzustellen dass der Exklusivmodus in jedem Fall zuverlässig wieder beendet wird. Dies kann über den Aufruf von ToolManager.setNonExclusive(Class<? extends Tool> toolClass) mit der entsprechenden Tool-Klasse erreicht werden. Da der Exklusiv-Modus für kurzzeitige komplexe Aktionen konzipiert ist, wird er in der Regel durch eine Tool-Implementierung selbstständig betreten und wieder verlassen.

Die bei einem ToolManager registrierten Tools können über verschiedene Methoden abgefragt werden. Im Besonderen kann auch das aktuell aktive Tool angefragt werden.

Beispiele für die Arbeit mit dem ToolManager finden sich unter „Verwendung des ToolManagers“.

Automatische Steuerung der Tool-Aktivierung

Neben einer expliziten Setzung des aktiven Tools über den ToolManager, wie es im vorhergehenden Abschnitt beschrieben wurde, besteht die Möglichkeit, das aktive Tool automatisch zu ermitteln. Zu diesem Zweck kann dem ToolManager eine Realisierung von ToolActivationPolicy bekannt gemacht werden. Soll auf ein Event reagiert werden, so befragt der ToolManager zunächst sämtliche Tools, ob sie auf dieses Event reagieren können. Alle Tools, bei denen die Antwort positiv ausfällt, werden in eine Liste aufgenommen. Diese wird an die gesetzte ToolActivationPolicy übergeben, welche wiederum das zu aktivierende Tool bestimmt.

Dieser Ansatz erlaubt beispielsweise ein automatisches Wechseln zwischen mehreren Modus-Tools.

Implementation eigener Tools

Jedes Tool ist eine Realisierung der abstrakten Klasse Tool. Wie einführend bereits erwähnt, haben Tools insgesamt vier Aufgabenbereiche:

  1. Teilnahme an der Zustandsverwaltung im Zusammenspiel mit dem ToolManager

  2. Verarbeitung von Eingabeereignissen

  3. Teilnahme am Rendering einer ViewComponent

  4. Beitragen von Menü- oder Symbolleistenelementen als MenuContributor

Bis auf den ersten Punkt sind alle Aufgaben optional. Tools müssen nicht auf Eingaben reagieren oder visuelle Beiträge zur Oberfläche liefern. Die folgenden Unterabschnitte gehen auf die genannten Punkte näher ein.

Zustandsverwaltung und -steuerung

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:

registriert

Tools, die nicht registriert sind, erhalten keine Ereignisse und können keine Funktionalität beisteuern. Zum Registrierungszeitpunkt wird einem Tool der zuständige ToolManager bekanntgemacht über die Methode Tool.setManager(ToolManager manager).

eingeschaltet

Tools, die nicht eingeschaltet sind, kennen zwar ihren ToolManager, erhalten aber keine Gelegenheit, ihre Funktionalität beizusteuern. Der Ein- oder Ausschaltevorgang wird einem Tool über die Methode Tool.setActive(boolean active) mitgeteilt.

aktiv

Tools, die vom Aktivitäts-Status abhängig sind – also insbesondere Modus-Tools – bekommen diesen über die Methode Tool.setActive(boolean active) mitgeteilt und können daraufhin entsprechend reagieren.

Zusätzlich werden Tools befragt, ob sie unter gegebenen Umständen Interesse an einer Aktivierung hätten. Diese Anfragen werden durch die ToolActivationPolicy ausgelöst und über die Methoden Tool.getActivationRequest…(…) sowie Tool.getActivationFeedback(MouseEditEvent e) gestellt. Die Antwort wird in Form einer Instanz von Tool.ActivationRequest gegeben.

exklusiv

Tools, die komplexe Operationen durchführen und während dieser Zeit keine Weitergabe von Events an andere Tools wünschen, können sich selbst als exklusives Tool setzen. Dies kann durch das Tool beim ToolManager beantragt werden. Tools, die sich selbst als exklusiv setzen, müssen sich diesen Status merken und zwingend dafür sorgen, dass der Exklusivmodus wieder zuverlässig verlassen wird. Des Weiteren sollten Tool-Implementationen darauf achten, den Exklusivmodus stets nur für möglichst kurze Zeiträume zu nutzen.

Eingabeereignisse

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:

  1. Tastatur-Events als Instanz von KeyEditEvent

  2. Mausrad-Events als Instanz von MouseWheelEditEvent

  3. Andere Maus-Events als Instanz von MouseEditEvent

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.

  • MouseEditEvent.getInputEvent().getPoint() entspricht den von AWT/Swing gewohnten Koordinaten in Pixeln, bezogen auf die obere linke Ecke der ViewComponent.

  • MouseEditEvent.getPoint() liefert die Bildschirmkoordinaten (Pixel) bezogen auf die obere linke Ecke der Seite, auf die sich das Event bezieht.

  • MouseEditEvent.getConstrainedPoint() liefert die gleichen Werte wie getPoint(), allerdings werden diese, wenn sich die Maus außerhalb einer Seite befindet, so begrenzt, dass der nächstgelegene Punkt innerhalb der nächstgelegenen Seite geliefert wird.

  • MouseEditEvent.getDocumentPoint() liefert die Dokumentkoordinaten, das heißt Koordinaten in Einheiten von Document.BASE_RESOLUTION, bezogen auf die obere linke Ecke der nächstgelegenen Seite.

  • MouseEditEvent.getConstrainedDocumentPoint() entspricht getDocumentPoint() mit dem Unterschied, dass die Koordinaten begrenzt werden, wie es auch bei getConstrainedPoint() der Fall ist.

Verteilungsreihenfolge und Konsumieren von Ereignissen

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.

Darstellung visueller Elemente (Rendering)

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.

Rendering-Reihenfolge

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.

Beiträge zum Kontextmenü

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.

Anwendungsbeispiele

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



[38] Aktuell existieren zwei Ausprägungen der ViewComponent: PageView und ThumbnailView. Weitere Informationen in „Anzeige von Dokumenten“.

[39] Allgemeine Informationen zu Drag&Drop finden sich unter „Drag&Drop“.

[40] Allgemeine Informationen zu Drag&Drop finden sich unter „Drag&Drop“.

[41] Zu Seitenlayouts (Klasse PageView.Layout) siehe „Seitenlayouts der PageView.

[42] Details finden sich unter PDF: Verschlüsselung“.

[43] Weitere Angaben zu Seiten in jadice gibt „Seiten in jadice“. Mit dem Thema RenderControls befasst sich „RenderControls und RenderSettings“.

[jadice viewer Version 6.1.37: Dokumentation für Entwickler. Veröffentlicht: 2024-11-11]