Dokumente und Partitionen

Das Textgerüst der Plattform definiert ein Dokumentmodell für Text und stellt eine Anzeigefunktion bereit, die Text unter Verwendung dieses Modells anzeigt. Zunächst wird die Verwendung dieses Modells anhand des Java-Beispieleditors vorgestellt.  Die Grundmechanismen für die Registrierung einer Editorerweiterung werden in diesem Zusammenhang nicht behandelt, da sie bereits in dem Abschnitt beschrieben wurden, der org.eclipse.ui.editors erläutert.  Stattdessen soll insbesondere erläutert werden, wie die Editorklasse im Beispiel implementiert wird.

Dokumentprovider und Dokumente

In der Workbench wird ein Editor normalerweise dann geöffnet, wenn der Benutzer ein Domänenelement (z. B. eine Datei oder ein Element, das in einer Archivdatei gespeichert ist) auswählt und öffnet.  Bei der Erstellung des Editors wird ihm ein Editoreingabeobjekt zugeordnet (IEditorInput), das das bearbeitete Objekt beschreibt.

Der Java-Beispieleditor wird geöffnet, wenn der Benutzer eine Datei mit der Erweiterung "*.jav" öffnet.  In diesem Fall ist die Eingabe für den Editor ein ObjektIFileEditorInput.  Das Textgerüst der Plattform benötigt nur wenige Angaben zur eigentlichen Editoreingabe.  Es arbeitet mit einem Darstellungsgerüst, dem so genanntenIDocument, für die Eingabe, damit Text tatsächlich angezeigt und bearbeitet werden kann.

Dies bedeutet, dass es eine Möglichkeit für die Zuordnung aus einem erwarteten Domänenmodell (der Editoreingabe) zum Darstellungsmodell geben muss.  Diese Zuordnung wird in einem Objekt IDocumentProvider definiert.  Der Dokumentprovider gibt für eine bestimmte Editoreingabe das passende ObjektIDocument zurück.

Der Java-Beispieleditor definiert ein Objekt JavaDocumentProvider, das das entsprechende Dokument zurückgibt.   Es stellt sich an dieser Stelle die Frage, wie nun die Beziehung zwischen dem Dokumentprovider und der Erweiterung "*.jav" eingerichtet wird. Dies erfolgt in der Erweiterungorg.eclipse.ui.documentProviders.   Mit dieser Erweiterung werden Zuordnungen zwischen Dateitypen und Dokumentprovidern definiert.   Das Beispiel definiert seinen Dokumentprovider folgendermaßen:

<extension
      point="org.eclipse.ui.documentProviders">
   <provider
         extensions="jav"
         class="org.eclipse.ui.examples.javaeditor.JavaDocumentProvider"
         id="org.eclipse.ui.examples.javaeditor.JavaDocumentProvider">
   </provider>
</extension>

Sobald der Benutzer eine Datei mit der angegebenen Erweiterung öffnet, verwaltet die Workbench die Details für die Erstellung des Dokumentproviderexemplars.  Die Workbench erstellt ein Dokumentproviderexemplar nur ein Mal und lässt dieses Exemplar von unterschiedlichen Editoren gemeinsam benutzen.

Es ist nicht erforderlich, dass Ihr Plug-in diesen Erweiterungspunkt für die Registrierung seines Dokumentproviders verwendet. Eine andere Möglichkeit für die Zuordnung eines Dokumentproviders zu einem Editor besteht darin, den Dokumentprovider vom Plug-in selbst verwalten zu lassen.  Dies erfolgt normalerweise in den Plug-in-Klassen.   Wenn ein Eingabeelement in den Editor gestellt wird, fordert dieser von seiner Plug-in-Klasse den entsprechenden Dokumentprovider an.  Das Plug-in kann die Erstellung und die Verweise auf den Dokumentprovider verwalten.  Diese Methode ist unter Umständen zu bevorzugen, wenn der Dokumentprovider eine spezielle Initialisierung oder andere Verarbeitungsschritte erforderlich macht.  Ein Beispiel finden Sie in den JDT-Tools unter ClassFileEditor.  

Nachdem einem Editor der richtige Dokumentprovider zugeordnet wurde, besteht seine Haupttask darin, aus der Editoreingabe ein Dokument zu erstellen sowie ein geeignetes Objekt zu erstellen, damit das Dokument in Partitionen untergliedert werden kann.   

Partitionen

Dokumente und Partitionen werden nun am Beispiel von JavaDocumentProvider erläutert.  Bei der Erstellung eines Dokuments wird ein ObjektIDocumentPartitioner erstellt und in das Dokument gestellt.  

protected IDocument createDocument(Object element) throws CoreException {
	IDocument document= super.createDocument(element);
	if (document != null) {
		IDocumentPartitioner partitioner= createJavaPartitioner();
		document.setDocumentPartitioner(partitioner);
		partitioner.connect(document);
	}
	return document;
}

Die Partitionierungsfunktion ist für die Unterteilung des Dokuments in nicht überlagernde Bereiche (so genannte "Partitionen") verantwortlich.  Partitionen (dargestellt unterITypedRegion) sind nützlich, wenn unterschiedliche Abschnitte des Dokuments im Hinblick auf Funktionen wie Syntaxhervorhebung oder Formatierung unterschiedlich verarbeitet werden sollen.

Im Beispiel des Java-Editors wird das Dokument in Partitionen unterteilt, die Javadoc-Kommentare, mehrzeilige Kommentare sowie alle übrigen Angaben darstellen.  Jedem Bereich ist ein Inhaltstyp und seine Position im Dokument zugeordnet.  Positionen werden aktualisiert, wenn der Benutzer den Text bearbeitet.   

Regelbasierte Dokumentpartitionierung

Jeder Editor muss selbst die geeignete Implementierung für eine Dokumentpartitionierungsfunktion bestimmen.  Die Unterstützung für ein regelbasiertes Dokumentscanning wird durchorg.eclipse.jface.text.rules bereitgestellt.  Mit einer regelbasierten Scannerfunktion kann ein Editor den DefaultPartitioner verwenden, der durch das Gerüst bereitgestellt wird.

private IDocumentPartitioner createJavaPartitioner() {
	return new DefaultPartitioner(getJavaPartitionScanner(), TYPES);
}

RuleBasedPartitionScanner ist die Superklasse für regelbasierte Scannerfunktionen.  Unterklassen sind für die Auflistung und die Implementierung der Regeln zuständig, mit denen Token wie Zeilenbegrenzer, Leerzeichen und generische Muster beim Durchsuchen eines Dokuments voneinander unterschieden werden.   Der JavaPartitionScanner des Beispiels definiert Regeln für die Unterscheidung von einzeiligen Kommentaren, Zeichenkonstanten, Javadoc, mehrzeiligen Kommentaren und  Maschinenwörtern.  Dies wird im Konstruktor der Scannerfunktion vorgenommen:

public JavaPartitionScanner() {
	super();
	IToken javaDoc= new Token(JAVA_DOC);
	IToken comment= new Token(JAVA_MULTILINE_COMMENT);

	List rules= new ArrayList();
	// Add rule for single line comments.
	rules.add(new EndOfLineRule("//", Token.UNDEFINED)); 

	// Add rule for strings and character constants.
	rules.add(new SingleLineRule("\"", "\"", Token.UNDEFINED, '\\')); 
	rules.add(new SingleLineRule("'", "'", Token.UNDEFINED, '\\')); 

	// Add special case word rule.
	rules.add(new WordPredicateRule(comment));

	// Add rules for multi-line comments and javadoc.
	rules.add(new MultiLineRule("/**", "*/", javaDoc, (char) 0, true)); 
	rules.add(new MultiLineRule("/*", "*/", comment, (char) 0, true)); 

	IPredicateRule[] result= new IPredicateRule[rules.size()];
	rules.toArray(result);
	setPredicateRules(result);
}

Weitere Details zum Definieren von Regeln und zu den verfügbaren Regeltypen können Sie in den Klassen von in org.eclipse.jface.text.rules nachlesen.   In dem Abschnitt, in dem die syntaxorientierten Textfarben behandelt werden, wird es auch noch einmal um die Scannerfunktionen gehen.

Anmerkungsmodelle

Neben der Bereitstellung eines geeigneten Dokuments für eine Editoreingabe hat ein Dokumentprovider außerdem die wichtige Aufgabe, ein passendes ObjektIAnnotationModel für die Verwendung mit der Editoreingabe zu liefern.  Mit diesem Modell werden die Anmerkungen verwaltet, die einem Dokument zugeordnet sind.  Indem der das Modell durch den Dokumentprovider bereitgestellt wird, kann der Editor ein für den Inhaltstyp geeignetes Modell verwenden.  Der nächste Abschnitt geht genauer auf Anmerkungen und deren Darstellung ein.

Copyright IBM Corporation und Andere 2000, 2003.