Mit dem Erweiterungspunkt org.eclipse.ui.newWizards können Sie in der Workbench einen Assistenten zur Menüoption Datei > Neu hinzufügen. Das Tool für Readme-Dateien verwendet diese Erweiterungspunktdefinition, um den Assistenten für Readme-Dateien hinzuzufügen:
<extension
point = "org.eclipse.ui.newWizards">
<category
id = "org.eclipse.ui.examples.readmetool.new"
name="Example Creation Wizards">
</category>
<wizard
id = "org.eclipse.ui.examples.readmetool.wizards.new.file"
name = "Readme File"
class="org.eclipse.ui.examples.readmetool.ReadmeCreationWizard"
category="org.eclipse.ui.examples.readmetool.new"
icon="icons/basic/obj16/newreadme_wiz.gif">
<description>An example of a wizard that creates sample Readme file
</description>
<selection class="org.eclipse.core.resources.IResource"/>
</wizard>
</extension>
Der Parameter category beschreibt, in welche Gruppe der Assistent gestellt wird, wenn der Assistentenauswahldialog verwendet wird, um einen Assistenten zu suchen und zu starten. Das unter "category" angegebene Attribut name ("Example Creation Wizard") definiert die Bezeichnung, die im Assistenten verwendet wird. Der Assistent selbst wird der angegebenen Kategorie zugeordnet. Im unten dargestellten Auswahldialog für einen neuen Assistenten werden sein Name, sein Symbol (icon) und seine Beschreibung (description) angezeigt.
Diese Angaben werden auf Grund der Befehlsdefinition in der Datei plugin.xml angezeigt. Kein Teil des Plug-in-Codes wird ausgeführt, bevor der Benutzer die Schaltfläche Weiter auswählt. Sobald dies stattfindet, erstellt die Workbench ein Exemplar der Klasse des Assistenten, die in der Befehlsdefinition angegeben ist, und übergibt an sie eine erwartete Auswahlklasse.
Die in dieser Erweiterung (ReadmeCreationWizard) angegebene Klasse muss die Schnittstelle INewWizard implementieren. In den meisten Assistenten wird zu diesem Zweck die Klasse Wizard der Plattform erweitert, obwohl es sich um einen Implementierungsmechanismus handelt und durch den Erweiterungspunkt nicht erfordert wird.
Der Assistent führt nichts weiter aus, als die in ihm enthaltenen Seiten zu erstellen. Im Folgenden wird zunächst die Implementierung der Seite erläutert. Anschließend kehren Sie zum Assistenten zurück.
Die Workbench bietet Basisklassen für Assistentenseiten, die den Typ der Verarbeitung unterstützen, die an einem bestimmten Assistentenerweiterungspunkt ausgeführt wird. Sie können diese Seiten unverändert verwenden oder sie durch das Hinzufügen einer weiteren Verarbeitung erweitern.
Der Zweck der Klasse ReadmeCreationWizard ist es, eine neue Datei zu erstellen, den erforderlichen Inhalt zur Datei hinzuzufügen und über eine Option einen Editor für die Datei zu öffnen. Die entsprechende Seite muss die Steuerelemente definieren, mit denen der Benutzer angeben kann, welcher Inhalt in die Datei gestellt und ob ein Editor gestartet werden soll.
Die Assistentenseite CreateReadmePage1 erstellen Sie nun, indem Sie die Klasse WizardNewFileCreationPage erweitern. Die Steuerelemente für eine Assistentenseite werden ähnlich wie die Steuerelemente für eine Sicht oder einen Editor definiert. Die Seite implementiert eine Methode createControl, mit der die erforderlichen SWT-Fensterobjekte als Kinder der bereitgestellten Klasse Composite erstellt werden. Da die Superklasse bereits Fensterobjekte hinzufügt, die die Verarbeitung einer neuen Datei unterstützen, müssen Sie lediglich die Methode createControl in der Assistentenseite erweitern und die zusätzlichen Markierungsfelder hinzufügen, mit denen das Generieren von Abschnitten und das Öffnen des Editors gesteuert wird.
public void createControl(Composite parent) {
// Standardfensterobjekte für Container- und Namensspezifikation übernehmen
super.createControl(parent);
Composite composite = (Composite)getControl();
...
// Gruppe zur Generierung von Beispielabschnitten
Group group = new Group(composite,SWT.NONE);
group.setLayout(new GridLayout());
group.setText("Automatic sample section generation");
group.setLayoutData(new GridData(GridData.GRAB_HORIZONTAL |
GridData.HORIZONTAL_ALIGN_FILL));
...
// Markierungsfelder für die Generierung von Beispielabschnitten
sectionCheckbox = new Button(group,SWT.CHECK);
sectionCheckbox.setText("Generate sample section titles");
sectionCheckbox.setSelection(true);
sectionCheckbox.addListener(SWT.Selection,this);
subsectionCheckbox = new Button(group,SWT.CHECK);
subsectionCheckbox.setText("Generate sample subsection titles");
subsectionCheckbox.setSelection(true);
subsectionCheckbox.addListener(SWT.Selection,this);
...
// Markierungsfeld für das Öffnen der Datei im Editor
openFileCheckbox = new Button(composite,SWT.CHECK);
openFileCheckbox.setText("Open file for editing when done");
openFileCheckbox.setSelection(true);
...
}
Wenn Sie mit den Konzepten, die unter SWT (Standard Widget Toolkit - Toolkit für Standardfensterobjekte) beschrieben sind, vertraut sind, sollten Sie in der Lage sein, diesen Code nachzuvollziehen.
Die Implementierung einer Seite umfasst die folgenden Grundmuster:
Listener-Funktionen zu allen Steuerelementen hinzufügen, die das dynamische Verhalten der Seite beeinflussen. Wirkt sich beispielsweise die Auswahl eines Listeneintrags oder eines Markierungsfelds auf den Status der anderen Steuerelemente der Seite aus, können Sie eine Listener-Funktion hinzufügen, damit der Satus der Seite geändert wird.
Steuerelemente mit Daten füllen, die auf der Auswahl basieren, die beim Starten des Assistenten gültig war. Manche Daten können von den Werten in anderen Steuerelementen abhängig sein. Einige Steuerelemente verwenden unter Umständen Dialogeinstellungen, um ihre Werte zu initialisieren.
Verwendung der Methode setPageComplete(true), sobald der Benutzer genügend Informationen zum Beenden der Seite (und zum Fortfahren mit der nächsten Seite bzw. zur Fertigstellung des Assistenten) bereitgestellt hat.
Die Klasse ReadmeCreationPage übernimmt einen Großteil dieses Verhaltens von der Klasse WizardNewFileCreationPage. Weitere Informationen finden Sie in den Implementierungen dieser Klassen.
Nachdem Sie jetzt die Funktionsweise einer Seite kennen gelernt haben, geht es wieder zurück zum Assistenten.
Der Assistent ist zuständig für die Erstellung der Seiten und für das Bereitstellen der Logik für die Fertigstellung.
Die Implementierung eines Assistenten umfasst die folgenden Grundmuster:
Implementierung der Methode init zur Definition von lokalen Variablen für Kontextinformationen wie beispielsweise Workbench und aktuelle Auswahl.
public void init(IWorkbench workbench,IStructuredSelection selection) {
this.workbench = workbench;
this.selection = selection;
setWindowTitle("New Readme File");
setDefaultPageImageDescriptor(ReadmeImages.README_WIZARD_BANNER);
}
Implementierung von der Methode addPages durch Erstellung von Exemplaren der Seiten.
public void addPages() {
mainPage = new ReadmeCreationPage(workbench, selection);
addPage(mainPage);
}
Implementierung von der Methode performFinish zur Fertigstellung der Task.
Mehrseitige Assistenten verarbeiten normalerweise die Fertigstellungslogik im Assistenten selbst, da jede Seite Informationen dazu beiträgt, auf welche Weise die Task implementiert wird. Einzelseitenassistenten können die Logik im Assistenten implementieren oder die Seite anweisen, den Job zu fertig zu stellen. Der von Ihnen gewählte Ansatz hängt zum großen Teil davon ab, wo der wichtige Status erhalten wird. Im Beispiel des Assistenten für die Readme-Datei soll die Seite angewiesen werden, die Verarbeitung fertig zu stellen.
public boolean performFinish() {
return mainPage.finish();
}
Der fertig gestellte Assistent sollte folgendermaßen aussehen: