Action und Command Framework

ActionRegistry & ActionManager sind deprecated und werden mit der nächsten Major Version entfernt.

Toolbars, Actions und Commands sind via GWT grundsätzlich via API konfigurierbar. Dies hat den Vorteil, dass der zugehörige Code in JavaScript übersetzt und sehr schnell geladen wird. Sowohl Buttons wie auch Kontextmenüeinträge setzen eine Action voraus. Für jedes Kommando sollte pro Kontext (ein Kontext wäre z.B. eine PageView) nur eine Action existieren. Um dies zu gewährleisten, müssen alle Actions über den ActionManager registriert werden. Weiterhin dient der ActionManager dem zentralen Reagieren auf Tastaturbefehle (KeyStrokes), sobald er mit einem Widget initialisiert wird.

Eventhandling

Die Events nehmen den vom Browser vorgesehenen Weg. GWT-Komponenten in diesem Pfad können Actions verarbeiten. Standardmäßig verarbeiten Buttons und Menüeinträge die KeyDownEvents und verarbeiten dadurch die Shortcuts. Da Buttons meist nicht direkt im Hirarchiepfad der JS-Key Events liegen gibt es die Hilfsklasse KeyDownEventDispatchingUtil. Damit werden die Events weitergereicht, wie beispielsweise an die darin enthaltene Toolbar. Wird die JWT-Toolbar verwendet, reicht auch diese die Events an alle enthaltenen Buttons weiter (gleiches gilt nun auch für Submenüs). Der Integrator ist für alles weitere selbst verantwortlich, und hat hier volle Freiheiten.

Der Viewer kann nun fokusiert werden. Verarbeitet kein Tool das ClickEvent auf den Viewer, so erhält der Viewer den Fokus. Die AnnotationToolbar hat ebenfalls einen Focus (für z.B. "Delete Anno"- Shortcut oder weitere folgende für "Fett" o.ä. wurde aber vorerst nicht eingebaut)

Ein Context ist nun zwingend. Existiert kein vom Intergrator erstellter Context in der Hirarchie, wird automatisch mit einer Warnung ein leerer Context im RootPanel angelegt und dieser verwendet.

Menüs & Toolbars

Menüs und Toolbars sollten grundsätzlich über den BasicMenuBuilder erstellt werden. Vordefinierte Actions, die zur Befüllung verwendet werden können, werden über die Klasse DefaultActions bereitgestellt.

Buttons

Buttons sollten nur in Ausnahmefällen unabhängig vom MenuBuilder erstellt werden; wenn, dann am besten über die Klassen JadiceDefaultButton und JadiceSubmenuButton:

mypanel.add(new JadiceDefaultButton(DefaultActions.pageNextAction(keyStroke, registry, context));

Nur in Ausnahmefällen sollte hierzu der JadiceButtonBuilder verwendet werden, da dieser die Actions nicht registriert und somit keine unmittelbare Tastaturbedienung der damit verbundenen Commands ermöglicht wird.

Actions

Actions stellen das Bindeglied zwischen der Benutzeroberfläche und den Commands dar. Sie enthalten die zur Anzeige wesentlichen Elemente wie Icon, Label, Beschreibung sowie die Keyboard-Shortcuts. Actions sind über die JadiceMessages lokalisierbar. Eine Vielzahl vorkonfigurierter Actions wird über die Klasse DefaultActions zur Verfügung gestellt.

Commands

Die Ausführung der meisten Viewer-Aktionen ist über zugehörige Commands gekapselt. Dies ermöglicht insbesondere die einfache Auslösung derselben Aktion über unterschiedliche UI-Komponenten. Beispielsweise kann der Zoom des Dokuments über einen Button, das Kontextmenü oder kundenspezifische Widgets angestoßen werden. Im Hintergrund wird dabei immer dasselbe Command verwendet.

Die folgende Liste gibt einen Überblick über die vorhandenen Commands und beinhaltet Links auf die zugehörige Javadoc-Dokumentation.

	Command	Funktion
Annotationen	AnnotationVisibilityCommand	Erlaubt das Ein- und Ausblenden von Annotationen (einzelne oder alle Annotationstypen).
	CreateAnnotationCommand	Erlaubt es, Annotationen zu erzeugen.
	CreateAnnotationViaApiCommand	Erzeugt Annotationen programmatisch via API.
	DeleteSelectedAnnotationsCommand	Löscht die aktuell selektierten Annotationen.
Auflösung	ShowResolutionCalibrationWidgetCommand	Blendet ein Popup zum individuellen Einstellen der Displayauflösung ein.
Bookmark	AddBookmarkCommand	Setzt ein Bookmark auf der aktuellen Seite.
	RemoveAllBookmarksCommand	Löscht alle Bookmarks, die auf dem aktuellen Dokument angebracht wurden.
	RemoveBookmarkCommand	Entfernt das Bookmark auf der aktuellen Seite.
	NextBookmarkCommand	Springt zum nächsten Bookmark innerhalb des Dokuments und zeigt die zugehörige Seite an.
	PreviousBookmarkCommand	Springt zum vorherigen Bookmark innerhalb des Dokuments und zeigt die zugehörige Seite an.
Gradation	ShowGradationCommand	Blendet ein Popup zum Justieren der Gradationskurve ein.
	GradationCurveCommand	Erlaubt das Manipulieren der Gradation anhand der graphischen Gradationskurve.
	GradationActionCommand	Erlaubt das Manipulieren der Gradation anhand von verschiedenen Aktionen.
Grid	AttachGridCommand	Erleichtert das Positionieren von Annotationen durch Ausrichtung an einem Grid.
Layout	SelectPageLayoutCommand	Erlaubt das Auswählen des aktuellen Seitenlayouts: Gitteransicht, fortlaufende Ansicht oder ganze Seite.
Locale	LocaleCommand	Schaltet die Sprache der Anwendung um.
Rotation	RotateCommand	Dreht die aktuelle Seite oder das Dokument auf einen vorgegebenen Winkel (Vielfache von 90 Grad).
	SpinCommand	Dreht die aktuelle Seite oder das Dokument um 90 Grad nach links oder rechts.
Seitenavigation	FirstPageCommand	Springt zur ersten Seite des Dokuments.
	LastPageCommand	Springt zur letzten Seite des Dokuments.
	NextPageCommand	Blättert eine Seite weiter.
	PreviousPageCommand	Blättert eine Seite zurück.
Suche	ActivateRolloutSearchCommand	Öffnet ein Popup zur Eingabe eines Suchbegriffs zur Textsuche im Dokument und in Annotationen.
	ActivateToolbarSearchCommand	Ermöglicht die Eingabe eines Suchbegriffs eingebettet in der Toolbar.
Tools	ActivateToolCommand	Aktiviert/deaktiviert ein gegebenes Tool.
	EnableToolCommand	Enabled/disabled ein gegebenes Tool.
	AutoActivationCommand	Aktiviert/deaktiviert die DefaultToolActivationPolicy welche für ein automatisches Aktivieren von Tools, wie z.B. dem PanForceMouseTool und dem TextSelectionTool sorgt.
	ThumbnailToolCommand	Aktiviert/deaktiviert und öffnet/schließt das ThumbnailTool.
Zoom	FitPageCommand	Wechselt in einen Seiten-Einpass-Modus. Solange der Modus nicht beendet wird, werden alle Seiten eingepasst – entweder komplett oder auf Seitenhöhe oder Seitenbreite.
	FitPageOnceCommand	Passt die aktuelle Seite in den aktuellen Anzeigebereich ein – entweder komplett oder auf Seitenhöhe oder Seitenbreite skaliert.
	ZoomCommand	Ermöglicht das relative Zoomen auf Dokument- und Seitenebenene. Details zur Integration und ein zugehöriges Codebeispiel finden sich in den Showcases unter "Commands / Buttons".
	ZoomToCommand	Ermöglicht das absolute Zoomen auf Dokument- und Seitenebene.

Anwendungsbereiche von Commands

Commands welche von der Klasse AbstractDocumentCommand erben können auf bestimmte Anwendungsbereiche begrenzt werden. Hierbei wird zwischen drei Werten des Enums Scope unterschieden: PAGE, DOCUMENT.

• PAGE

  Änderungen an den RenderControls die von einem Command mit Scope.PAGE ausgeführt werden, verändern nur die Darstellung der aktuellen Seite, nicht aber von anderen Dokumentbestandteilen.

• DOCUMENT

  Änderungen an den RenderControls die von einem Command mit Scope.DOCUMENT ausgeführt werden, verändern nur die Darstellung des aktuellen Dokumentes. Wird ein neues Dokument geöffnet, so sind diese Änderungen nicht länger wirksam.

Standardmäßig wird der Anwendungsbereich Scope.DOCUMENT verwendet.

Keyboard Shortcuts

Das Action und Command Framework erlaubt die einfache Nutzung von Keyboard Shortcuts.

Event Handling im Browser

Bei der Eingabe einer Tastenkombination (z.B. Strg + P) wird vom Browser ein KeyDownEvent an das body-Element des DOMs geschickt, das in GWT durch die Klasse RootPanel repräsentiert wird.

Kommandos sind in jadice web toolkit mit den zugehörigen Actions in der Toolbar verknüpft. Um ein Kommando via Shortcut auszuführen, muss daher das KeyDownEvent an die den Button beinhaltende Toolbar weitergereicht werden. Diese Benachrichtigung kann über die Klasse KeyDownEventDispatchingUtil erfolgen (siehe Codebeispiel unten).

Der Shortcut "Strg + P" ist in diversen Browsern mit einem proprietären Druckdialog vorbelegt. Typischerweise soll bei der Verknüpfung eines Shortcuts mit einem jadice web toolkit spezifischen Kommando eine etwaige Vorbelegung ausgeschaltet werden. Die Nutzung des KeyDownEventDispatchingUtil stellt dies sicher.

Definition eines Shortcuts

Das folgende Codebeispiel demonstriert die Verknüpfung des Shortcuts "Strg + P" mit dem PrintStreamCommand aus der Demo Basicviewer.

Einrichten des Shortcuts "Strg + P" für das PrintStreamCommand:

    HorizontalToolbar toolbar = new HorizontalToolbar();
    toolbar.add(
           new RegisteredAction(description, new KeyStroke(Keys.P, Modifier.CTRL),
            new StateEffectIcon(EffectIcons.getEffectIcon(buttonResources.iconDownloadTiff())), 
            new PrintStreamCommand(Type.TIFF), context);
        );
    KeyDownEventDispatchingUtil.dispatch(RootPanel.get(), toolbar);

Der Methode KeyDownEventDispatchingUtil.dispatch() werden als Parameter das Quellwidget sowie eine beliebige Anzahl von Zielwidgets übergeben. Alle KeyDownEvents, die dem Quellwidget vom Browser zugestellt werden, werden an die Zielwidgets weitergereicht und können dadurch von den verknüpften Kommandos verarbeitet werden.