Wizards

Aus Eclipse
Wechseln zu: Navigation, Suche

Allgemeines

Viele Anwender kennen Wizards aus den Installationsroutinen von Programmen. Es sind modale Fenster mit Back-, Next-, Finish- und Cancel-Button. Der Benutzer wird Schrittweise aufgefordert Informationen anzugeben.

Als Beispiel dient der Wizard aus dem Eclipse Corner Article:

Ein Urlaub soll per Wizard gebucht werden. Der Benutzer trifft seine Auswahl und kommt durch betätigen des Next-Buttons zur nächsten Seite. Möchte er seine Angaben korrigieren, kann er mit dem Back-Button zur letzten Eingabeseite gelangen.

Wizard-Klassen-Hierarchie

thumg


Um einen Wizard zu erstellen wird eine Subklasse der Klasse Wizard (org.eclipse.jface.wizard.Wizard) erzeugt. Diese Implementiert das IWizard-Interface (org.eclipse.jface.wizard.IWizard) um die Klasse WizardDialog zu nutzen.

Die WizardDialog-Klasse benutzt wiederum das IWizard-Interface um die einzelnen Pages des Wizards zu erhalten und den Wizard über Benutzer-Interaktionen zu informieren.

Die eigentliche Wizard-Klasse erstellt und initialisiert die Wizard-Pages, verwaltet die Abläufe und Informationen zwischen den einzelnen Pages und führt die Operation aus wenn der Finish-Button gedrückt wurde.

Methoden von IWizard

addPages()
Hinzufügen einer Wizard-Seite

canFinish()
Überprüft, ob alle notwendigen Benutzereingaben vorhanden sind. Diese Methode wird vor allem eingesetzt, um den Finish-Button zu aktivieren bzw. zu deaktivieren.

createPageControls(Composite pageContainer)
Erstellt die Kontroll-Buttons

dispose()
Schließt den Wizard und gibt alle verwendeten SWT-Ressourcen wieder frei

getContainer()
Gibt den Wizard-Container zurück indem der Wizard gerade angezeigt wird

getDefaultPageImage()
Gibt das Standard-Seite-Bild für diesen Wizard zurück

getDialogSettings()
Gibt die Einstellungen des Dialogs für diesen Wizard zurück

getNextPage(IWizardPage)()
Gibt die Wizard-Seite zurück, die als nächstes angezeigt wird. Falls keine Seite mehr vorhanden ist, wird null zurückgegeben. Die Standard-Implementierung eines Wizards zeigt die Seiten in der Reihenfolge an, in der sie hinzugefügt wurden. Um eine gute Seiten-Abfolge zu erhalten, müssen Subklassen also lediglich diese Methode überschreiben.

getPreviousPage()
Gibt die Wizard-Seite zurück, die sich vor dieser Seite befindet. Falls diese Seite nicht existiert wird null zurückgegeben.

getStartingPage()
Gibt die erste Seite des Wizards zurück.

performCancel()
Diese Aktion wird ausgeführt falls der Benutzer die Cancel-Taste drückt. Es wird true zurückgegeben falls der Wizard geschlossen werden kann, ansonsten false (Wizard bleibt in diesem Fall geöffnet).

performFinish()
Diese Aktion wird ausgeführt falls der Benutzer die Finish-Taste drückt. Subklassen sollten diese Methode überschreiben um die Finish-Operation auszuführen und true (Wizard soll geschlossen werden) bzw. false (Wizard soll geöffnet bleiben) zurückgeben.

setDefaultPageImageDescriptor(ImageDescriptor)
Wenn der Wizard kein Bild in der Title Area anzeigt wird durch diese Methode ein Bild angezeigt.

setHelpAvailable(boolean)
true: Help-Button ist sichtbar und Hilfe kann angezeigt werden false: Help-Button ist nicht sichtbar, es wird keine Hilfe angeboten

setNeedsProgressMonitor(boolean)
true: Es soll eine Anzeige zur Visualisierung des Fortschritts angezeigt werden. Dazu wird Platz unterhalb der Page Area und oberhalb der Button Area für Fortschrittsanzeige und Fortschrittsnachricht reserviert

setTitleBarColor(RGB)
Färbt die Title Area mit der gwählten Farbe ein

setWindowTitle(String)
Titel des Wizards wird im Fenster angezeigt

IWizardPage und deren Methoden

Wie schon erwähnt benutzt ein Wizard das IWizardPage-Interface (org.eclipse.jface.wizard.IWizardPage) um mit den Wizard-Seiten zu kommunizieren. Üblicherweise wird eine Subklasse von der WizardPage-Klasse (org.eclipse.jface.wizard.WizardPage) erzeugt. Anstatt das IWizardPage-Interface zu implementieren werden die folgenden Methoden werden benutzt bzw. überschrieben:

createControl(Composite)
Erstellt die Wizard-Kontrollen

dispose()
Gibt alle Ressourcen, die von dieser Klasse erzeugt wurden, wieder frei. Dabei handelt es sich um Bilder, Clipboards usw.

getContainer()
Gibt den Wizard-Container für diese Wizard-Seite zurück

getDialogSettings()
Gibt die Dialog-Einstellungen für diese Wizard-Seite zurück

getWizard()
Gibt den Wizard zurück, dem diese Wizard-Seite zugeteilt ist

setDescription(String)
Zeigt die Beschreibung dieser Wizard-Seite in der Wizard Title Area an

setErrorMessage(String)
Erzeugt oder löscht die Fehlermeldung für diese Wizard-Seite

setImageDescriptor(ImageDescriptor)
Bestimmt das Bild welches in der Title Area angezeigt wird

setMessage(String)
Erzeugt oder löscht eine Nachricht für diese Wizard-Seite

setPageComplete(boolean)
true: alle notwendigen Benutzereingaben für diese Wizard-Seite sind erfolgt false: es fehlen noch Benutzereingaben

Basis für die Anzeige des Next- bzw. Finish-Buttons!

setTitle(String)
Zeigt den Titel in der Title Area des Wizards an

setVisible(boolean)
true: die Dialog-Seite wird angezeigt false: die Dialog-Seite wird nicht angezeigt

Eine Möglichkeit um Benutzer-Eingaben auf einer Wizard-Seite zu überprüfen sind Listener. Diese werden für jedes Feld implementiert:

Listener wird zugewiesen
Listener-Ereignis wird abgefangen und behandelt

IWizardContainer und dessen Methoden

Der IWizardContainer (org.eclipse.jface.wizard.IWizardContainer) ist ein Interface zur Aufnahme eines Wizards. Üblicherweise wird die aktuelle Seite (current page) des Wizards angezeigt. Die Seiten müssen dabei nicht alle ein und demselben Wizard gehören.

Die WizardDialog-Klasse stellte eine voll funktionstüchtige Implementation dieses Interfaces zur Verfügung. Diese sollte den meisten Ansprüchen genügen.

getCurrentPage()
Gibt die aktuell angezeigte Wizard-Seite zurück

getShell()
Gibt die Shell für den Wizard Container zurück

run(boolean,boolean,IRunnableWithProgress)
Führt die Anweisungen im Kontext des Wizard-Dialogs aus. Das erste boolean-Argument "fork" gibt an ob ein separater Thread gestartet werden soll. Das zweite boolean-Argument "cancelable" gibt an ob die Operation abgebrochen werden darf.

showPage(IWizardPage)
Zeigt die übergebene Wizard-Seite an. Diese Methode sollte allerdings nicht für normale next/back-Seiten-Folgen benutzt werden. Viel mehr sollte diese Methode für Ereignisse wie Doppelklicks auf Listen genutzt werden.

updateButtons()
Regelt den Status der Back-, Next- und Finish-Buttons

updateMessage()
Aktualisiert die angezeigte Nachricht

updateTitleBar()
Aktualisiert die Title Bar (Titel, Beschreibung und Bild)

updateWindowTitle()
Aktualisiert den Fenstertitel

Einbettungsmöglichkeiten von Wizards

Ein Wizard kann auf zwei verschiedene Arten im Eclipse-Framework eingebettet werden. Einerseits geschieht das durch die Benutzung vordefinierter Wizard Extension Points, andererseits durch manuelles Starten eines Wizards in Folge einer Benutzeraktion.

Wizard Extension Points

Um einen Wizard in Eclipse an einem vordefinierten Ort einzubetten, bieten sich die unten stehenden Wizard Extension Points an.

org.eclipse.ui.exportWizards
Fügt einen eingebetteten Wizard im Export-Wizard ein. Dieser wird unter File > Export... angezeigt:

Wizard-Klassen, die diesen Extension Point nutzen wollen, müssen das Interface org.eclipse.ui.IExportWizard implementieren!

org.eclipse.ui.importWizards
Wird unter File > Import... angezeigt:

Wizard-Klassen, die diesen Extension Point nutzen wollen, müssen das Interface org.eclipse.ui.IImportWizard implementieren!

org.eclipse.ui.newWizards
Wird unter File > New > Other... angezeigt:

Wizard-Klassen, die diesen Extension Point nutzen wollen, müssen das Interface org.eclipse.ui.INewWizard implementieren!

Mit Hilfe des Plug-In-Manifest-Editors können in relativ kurzer Zeit Wizard-Klassen erzeugt werden:

Extension.png


Manuelles Starten eines Wizards

Um einen Wizard manuell zu starten kann entweder IHandler implementiert werden oder AbstractHandler erweitert werden. Eine execute-Methode führt den Extract Strings Wizard aus:

Manually.png