⯇ Vorheriges Tutorial

In 2 - Laden eines Dokuments haben wir erfolgreich unser erstes Dokument geladen. In diesem Tutorial wollen wir eine Toolbar einbinden und folgende Standard-Funktionen hinzufügen:

• Vergrößeren / Verkleinern des Dokuments
• Nächste / Vorherige Seite

Das Ergebnis des Tutorials kann in https://github.com/levigo/jwt-getting-started/tree/master/jwt-tutorial-003 überprüft werden.

Projektstruktur

Folgende Klassen passen wir in diesem Tutorial an:

└── src/main/java/                      
    └── org/jwt/
        └── client/
            └── ui/                         
                └── JadiceWidget.java

Action und Command Framework

Bevor wir mit der Implementierung beginnen, widmen wir uns kurz dem Action und Command Framework von jadice. Folgende Konzepte müssen wir verstehen:

• Command
  Ein Command implementiert die tatsächliche Viewer-Funktionalität, wie die Auswahl der nächsten Seite.
• Action
  Die Action bindet einen Command an die GUI-Komponente, z.B. einen Button. Der Action können wir ein Label, Icon und Tastaturkürzel zuweisen.
• Context
  Der Kontext (Context) dient der Entkopplung unserer GUI-Komponenten. Dem Kontext können wir alle wichtigen Komponenten hinzufügen. So müssen wir nicht mehr die Implementierungsdetails eines Commands kennen. Stattdessen holt sich der Command die benötigten Komponenten selbst aus dessen Kontext.

Eine ausführliche Beschreibung und weitere Details finden sich in den folgenden Links:

• Referenzhandbuch - Action und Command Framework
• Referenzhandbuch - Context
• Der levigo-utils GUI-Context

Kontext (Context)

Bevor wir die Toolbar einbinden, müssen wir unseren Kontext initialisieren. Dazu rufen wir Context.install() mit unserem JadiceWidget als Owner auf. Da alle unsere Standard-Funktionen die PageView zur Interaktion mit dem Dokument benötigen (sie erben alle von AbstractPageViewCommand), fügen wir die PageView dem Kontext hinzu.

private void init() {
        ...
        // initialize the context and register the PageView
        Context context = Context.install(this, Children.ALL, Ancestors.ALL);
        context.add(viewer.getPageView());
        
		panel.add(viewer);
    }

In einigen Situation ist es evtl. sinnvoll mehrere Kontexte zu nutzen, z.B. bei der Anzeige von zwei Viewern. Hier müssen wir explizit darauf achten den korrekten Kontext zu übergeben.

Toolbar und DefaultActions

In unserem Beispiel erstellen wir eine horizontale Toolbar (HorizontalToolbar). Anschließend fügen wir Buttons mit unseren Commands hinzu:

    protected AbstractBar createToolbar(final Context context) {
        final HorizontalToolbar toolbar = new HorizontalToolbar();

        toolbar.add(new JadiceDefaultButton(DefaultActions.zoomInAction(new KeyStroke(Keys.PLUS), context)));
        toolbar.add(new JadiceDefaultButton(DefaultActions.zoomOutAction(new KeyStroke(Keys.MINUS), context)));
        toolbar.addSeparator();
        toolbar.add(new JadiceDefaultButton(DefaultActions.pagePrevAction(new KeyStroke(Keys.LEFT), context)));
        toolbar.add(new JadiceDefaultButton(DefaultActions.pageNextAction(new KeyStroke(Keys.RIGHT), context)));

        return toolbar;
    }

Ein kurzer Überblick über unseren Code:

• context
  Den Kontext haben wir oben erklärt. Er wird uns vom Aufrufer übergeben.
• DefaultActions
  In den DefaultActions sind vorkonfigurierte Actions aller von JWT mitgelieferten Commands verfügbar. Sie enthalten bereits passende Labels und Icons.
• DefaultActions.zoomInAction() (zoomOutAction(), pagePrevAction(), pageNextAction())
  Beim Erstellen unserer Actions übergeben wir jeweils unser gewünschtes Tastaturkürzel (new KeyStoke(Keys.PLUS)) und den Kontext.
• new JadiceDefaultButton()
  Unsere Actions hängen wir über einen JadiceDefaultButton an die Toolbar. Der JadiceDefaultButton kann den Zustand des Commands anzeigen, z.B. aktiviert, deaktiviert oder selektiert.

• addSeparator()
  Zwischen den Zoom-Buttons und Navigation-Buttons fügen wir mit addSeparator() einen optischen Trenner ein.

Als letztes müssen wir die Toolbar noch in unsere Oberfläche hängen. Dazu ergänzen wir erneut die Methode JadiceWidget.init(). Wir fügen die Toolbar oben an unseren Viewer über panel.addNorth(). Wichtig ist, dass die Hauptkomponente, in unserem Fall der Viewer, als letztes hinzugefügt wird. Unser Code sieht dann so aus:

    private void init() {
        ...

        // create the toolbar and add it to the panel
        AbstractBar toolbar = createToolbar(context);
        panel.addNorth(toolbar, toolbar.getStyle().size());

        panel.add(viewer);
    }

Zusammenfassung

In diesem Tutorial hatten wir ersten Kontakt mit dem Action und Command Framework sowie dem jadice Kontext. Mit dieser Grundlage konnten wir den Viewer um eine Toolbar ergänzen und können nun zwischen Seiten navigieren und zoomen.

⯇ Vorheriges Tutorial