Die Workbench implementiert eine generische Architektur für Benutzervorgaben, mit deren Hilfe Plug-ins Werte für Benutzervorgaben speichern und den Benutzervorgabendialog der Workbench durch eine Benutzervorgabenseite ergänzen können. Diese Verwendung soll erneut anhand des Tools für Readme-Dateien veranschaulicht werden. Anschließend wird die zu Grunde liegende Unterstützung für die Erstellung von Benutzervorgabenseiten näher vorgestellt.
Am Erweiterungspunkt org.eclipse.ui.preferencePages können Sie den Benutzervorgabendialog der Workbench (Fenster > Benutzervorgaben) durch Seiten ergänzen. Der Benutzervorgabendialog stellt eine hierarchische Liste der Einträge für die Benutzervorgaben dar. Jeder Eintrag zeigt bei seiner Auswahl eine entsprechende Benutzervorgabenseite an.
Das Tool für Readme-Dateien verwendet diesen Erweiterungspunkt, um die Benutzervorgabenseite "Readme Example" hinzuzufügen.
<extension
point = "org.eclipse.ui.preferencePages">
<page
id="org.eclipse.ui.examples.readmetool.Page1"
class="org.eclipse.ui.examples.readmetool.ReadmePreferencePage"
name="Readme Example">
</page>
</extension>
Diese Befehle definieren eine Benutzervorgabenseite namens "Readme Example", die durch die Klasse ReadmePreferencePage implementiert wird. Die Klasse muss die Schnittstelle IWorkbenchPreferencePage implementieren.
Die Workbench verwendet eine Klasse PreferenceManager, um eine Liste aller Knoten in der Baumstruktur der Benutzervorgaben und ihrer entsprechenden Seiten zu verwalten. Diese Liste kann aus Informationen in der Plug-in-Registrierung initialisiert werden, ohne dass ein Plug-in-Code ausgeführt werden muss. Die Ergänzung, die durch Ihr Plug-in für den Benutzervorgabendialog (Eintrag "Readme Example" auf der linken Seite) bereitgestellt wird, wird angezeigt, bevor der Code ausgeführt wird.
Die Benutzervorgabe "Readme Example" wird auf der obersten Ebene der Baumstruktur für die Benutzervorgaben, die auf der linken Seite angezeigt wird, hinzugefügt. Dies liegt daran, dass eine Ergänzung durch eine Benutzervorgabenseite als Stammebene der Baumstruktur hinzugefügt wird, wenn das Attribut category nicht angegeben wurde. (Der Name category ist etwas irreführend). Ein besserer Name wäre vielleicht path (=Pfad).) Das Attribut category gibt die ID (oder eine Folge von IDs aus dem Stamm) der Elternseite an. Die folgende Befehlsdefinition würde beispielsweise eine zweite Benutzervorgabenseite für das Tool für Readme-Dateien (namens "Readme Example Child Page") als Kind der Originalseite erstellen.
<extension
point = "org.eclipse.ui.preferencePages">
<page
id="org.eclipse.ui.examples.readmetool.Page1"
class="org.eclipse.ui.examples.readmetool.ReadmePreferencePage"
name="Readme Example">
</page>
<page
id="org.eclipse.ui.examples.readmetool.Page2"
class="org.eclipse.ui.examples.readmetool.ReadmePreferencePage2"
name="Readme Example Child Page"
category="org.eclipse.ui.examples.readmetool.Page1>
</page>
</extension>
Sobald der Benutzer den Eintrag für eine Benutzervorgabenseite in der Baumstruktur auf der linken Seite auswählt, erstellt die Workbench mit Hilfe der Klasse, die in der Erweiterungsdefinition angegeben ist, eine Benutzervorgabenseite und zeigt diese an. Diese Aktion aktiviert das Plug-in (sofern es nicht bereits durch eine andere Benutzeraktion aktiviert war).
Die Implementierung einer Benutzervorgabenseite ähnelt der Erstellung einer Seite für einen Assistenten. Die Benutzervorgabenseite stellt eine Methode createContents bereit, die die SWT-Steuerelemente erstellt, mit denen der Seiteninhalt dargestellt wird, und die Listener-Funktionen für alle wichtigen Ereignisse hinzufügt. Die Seite ist für die Erstellung und Rückgabe des kombinierten Steuerelements zuständig, das das Elter aller Steuerelemente auf der Seite ist. Der folgende Ausschnitt enthält die wichtigen Punkte:
protected Control createContents(Composite parent)
{
...
//composite_textField << parent
Composite composite_textField = createComposite(parent, 2);
Label label_textField = createLabel(composite_textField, "Text Field");
textField = createTextField(composite_textField);
pushButton_textField = createPushButton(composite_textField, "Change");
//composite_tab << parent
Composite composite_tab = createComposite(parent, 2);
Label label1 = createLabel(composite_tab, "Radio Button Options");
tabForward(composite_tab);
//radio button composite << tab composite
Composite composite_radioButton = createComposite(composite_tab, 1);
radioButton1 = createRadioButton(composite_radioButton, "Radio button 1");
radioButton2 = createRadioButton(composite_radioButton, "Radio button 2");
radioButton3 = createRadioButton(composite_radioButton, "Radio button 3");
...
initializeValues();
...
return new Composite(parent, SWT.NULL);
}
Der meiste Code in dieser Methode dient der Erstellung und Anordnung der Steuerelemente und soll daher an dieser Stelle nicht näher behandelt werden. Die entsprechende Seite für diesen Code sieht folgendermaßen aus:
Eine weitere wichtige Aufgabe einer Benutzervorgabenseite ist die Reaktion auf die Nachricht der Methode performOk. Normalerweise aktualisiert und speichert diese Methode die Benutzervorgaben und aktualisiert gegebenenfalls andere Plug-in-Objekte, um die Änderungen in den Benutzervorgaben umzusetzen.
Benutzervorgabenseiten sollten die Methode doGetPreferenceStore() überschreiben, damit ein Benutzervorgabenspeicher für ihre Werte zurückgegeben wird.
Benutzervorgabenspeicher sind in vielen Punkten mit Dialogeinstellungen vergleichbar. Im Abschnitt Dialogeinstellungen wurde bereits erläutert, wie die Klasse AbstractUIPlugin die Dialogeinstellung während der Lebensdauer eines Plug-ins verwaltet. Dieselbe Strategie wird bei Benutzervorgaben angewandt. Ihr Plug-in kann Einträge zu einem Benutzervorgabenspeicher hinzufügen und die Werte aktualisieren, wenn der Benutzer die Einstellungen auf der Benutzervorgabenseite ändert. Die Plattform übernimmt das Speichern dieser Werte im Arbeitsverzeichnis des Plug-ins und die Initialisierung des Benutzervorgabenspeichers aus den gespeicherten Einstellungen.
Der folgende Code in ReadmePreferencePage ruft den Benutzervorgabenspeicher für ReadmePlugin ab.
protected IPreferenceStore doGetPreferenceStore() {
return ReadmePlugin.getDefault().getPreferenceStore();
}
Da ReadmePlugin die Klasse AbstractUIPlugin erweitert, wird automatisch ein Benutzervorgabenspeicher übernommen. Dieser Benutzervorgabenspeicher wird aus einer Benutzervorgabendatei initialisiert, die im Verzeichnis des Plug-ins gespeichert ist. ReadmePlugin muss jetzt nur noch eine Methode implementieren, die die Benutzervorgaben mit den Standardwerten initialisiert. Diese Werte werden verwendet, wenn die Benutzervorgabenseite zum ersten Mal angezeigt wird oder der Benutzer auf der Benutzervorgabenseite die Schaltfläche Standardwerte auswählt.
protected void initializeDefaultPreferences(IPreferenceStore store) {
// Diese Einstellungen werden angezeigt, wenn der Dialog
// Benutzervorgaben zum ersten Mal geöffnet wird.
store.setDefault(IReadmeConstants.PRE_CHECK1, true);
store.setDefault(IReadmeConstants.PRE_CHECK2, true);
store.setDefault(IReadmeConstants.PRE_CHECK3, false);
store.setDefault(IReadmeConstants.PRE_RADIO_CHOICE, 2);
store.setDefault(IReadmeConstants.PRE_TEXT, "Default text");
}
Hinweis: Wenn für ein Plug-in keine Benutzervorgaben gespeichert wurden, erhält das Plug-in einen leeren Benutzervorgabenspeicher.
Sobald Sie der Benutzervorgabenseite Ihres Plug-ins einen Benutzervorgabenspeicher zugeordnet haben, können Sie die Logik für das Abrufen und Speichern der Benutzervorgaben implementieren.
Benutzervorgabenseiten haben die Aufgabe, die Werte ihrer Steuerelemente mit den Einstellungen aus dem Benutzervorgabenspeicher zu initialisieren. Dieser Prozess ist mit dem Initialisieren von Dialogsteuerelementen mit Werten aus Dialogeinstellungen vergleichbar. ReadmePreferencePage initialisiert alle Steuerelemente in einer einzigen Methode namens initializeValues, die aus der Methode createContents heraus aufgerufen wird.
private void initializeValues() {
IPreferenceStore store = getPreferenceStore();
checkBox1.setSelection(store.getBoolean(IReadmeConstants.PRE_CHECK1));
checkBox2.setSelection(store.getBoolean(IReadmeConstants.PRE_CHECK2));
checkBox3.setSelection(store.getBoolean(IReadmeConstants.PRE_CHECK3));
...
Sobald die Schaltfläche OK (oder Übernehmen) ausgewählt wird, sollten die aktuellen Werte der Steuerelemente auf der Benutzervorgabenseite wieder im Benutzervorgabenspeicher gespeichert werden. ReadmePreferencePage implementiert diese Logik in einer separaten Methode namens storeValues.
private void storeValues() {
IPreferenceStore store = getPreferenceStore();
store.setValue(IReadmeConstants.PRE_CHECK1, checkBox1.getSelection());
store.setValue(IReadmeConstants.PRE_CHECK2, checkBox2.getSelection());
store.setValue(IReadmeConstants.PRE_CHECK3, checkBox3.getSelection());
...
}
Wenn der Benutzer die Schaltfläche Standardwerte auswählt, setzt die Plattform alle Werte im Benutzervorgabenspeicher auf die Standardwerte zurück, die in der Plug-in-Klasse angegeben sind. Die Benutzervorgabenseite muss jedoch dafür sorgen, dass diese Standardwerte in den Steuerelementen der Benutzervorgabenseite wiedergegeben werden. ReadmePreferencePage implementiert diese Aufgabe in der Methode initializeDefaults.
private void initializeDefaults() {
IPreferenceStore store = getPreferenceStore();
checkBox1.setSelection(store.getDefaultBoolean(IReadmeConstants.PRE_CHECK1));
checkBox2.setSelection(store.getDefaultBoolean(IReadmeConstants.PRE_CHECK2));
checkBox3.setSelection(store.getDefaultBoolean(IReadmeConstants.PRE_CHECK3));
...
}
Die Implementierung einer Benutzervorgabenseite besteht primär aus SWT-Code. Mit SWT-Code werden die Steuerelemente der Benutzervorgabenseite erstellt, die Werte der Steuerelemente festgelegt und die Werte der Steuerelemente abgerufen. Das Paket org.eclipse.jface.preferencestellt Klassen für Hilfeprogramme, so genannte Feldeditoren, zur Verfügung, die die Fensterobjekte erstellen sowie die Werteinstellung und den Abrufcode für die meisten gängigen Benutzervorgabentypen implementieren. Die Plattform bietet Feldeditoren zum Anzeigen und Aktualisieren von vielen Werttypen, inklusive Boolescher Werte, Farben, Zeichenfolgen, Integer, Schriftarten und Dateinamen.
Die Klasse FieldEditorPreferencePage implementiert eine Seite, die diese Feldeditoren einsetzt, um die Benutzervorgabenwerte auf der Seite anzuzeigen und zu speichern.
Statt den Inhalt durch die Erstellung von SWT-Steuerelementen zu füllen, erstellt die Klasse FieldEditorPreferencePage Feldeditoren, die den Inhalt anzeigen.
public void createFieldEditors() {
// Die erste Zeichenfolge ist der Schlüsselname für die Benutzervorgabe.
// Die zweite Zeichenfolge ist die Bezeichnung, die neben dem Fensterobjekt angezeigt wird.
addField(new BooleanFieldEditor(USE_OLD_MODE, "Use old mode",
getFieldEditorParent()));
addField(new StringFieldEditor(APPLICATION_NAME, "Application Name",
getFieldEditorParent()));
addField(new ColorFieldEditor(COLOR, "Text Color", getFieldEditorParent()));
...
Jedem Feldeditor ist der Name des entsprechenden Schlüssels für die Benutzervorgabe und die Textbezeichnung für das SWT-Fensterobjekt zugeordnet, das durch ihn erstellt wird. Der Typ des erstellten Steuerelements ist vom Typ des Feldeditors abhängig. Ein Boolescher Feldeditor erstellt z. B. ein Markierungsfeld.
Da der Benutzervorgabenseite ein Benutzervorgabenspeicher zugeordnet ist (angegeben in der Methode doGetPreferenceStore), kann der gesamte Code für das Speichern der aktuellen Werte, die Initialisierung der Steuerelementwerte aus dem Benutzervorgabenspeicher und das Zurücksetzen der Steuerelemente auf die Standardwerte in der Klasse FieldEditorPreferencePage implementiert werden.
Die Klasse FieldEditorPreferencePage verwendet ein Rasterlayout mit 1 Spalte als Standardlayout für Feldeditorfensterobjekte. Wenn Sie ein spezielles Layout benötigen, können Sie die Methode createContents überschreiben.