Dokumenter og partisjoner

Tekstrammeverket for plattformen definerer en dokumentmodell for tekst og inneholder et visningsprogram som viser tekst ved hjelp av denne modellen. Vi skal først se nærmere på Java-redigeringsprogrameksempelet og hvordan det bruker denne modellen. Vi vektlegger ikke den grunnleggende funksjonen for registrering av en redigeringsprogramutvidelse siden dette beskrives i avsnittet om org.eclipse.ui.editors. Vi skal i stedet se hvordan redigeringsprogramklassen implementeres i eksempelet.

Dokumentleverandører og dokumenter

Et redigeringsprogram i arbeidsbenken åpnes vanligvis når brukeren velger et domeneelement (for eksempel en fil eller et element som er lagret i en arkivfil) og åpner det.  Når redigeringsprogrammet opprettes, blir det tilknyttet inndata for redigeringsprogram (IEditorInput), som beskriver objektet som redigeres.

Java-redigeringsprogrameksempelet åpnes når brukeren åpner en fil med filtypen "*.jav".   I dette tilfellet er inndataene til redigeringsprogrammet en IFileEditorInput.  I tekstrammeverket for plattformen antas det ingenting om selve inndataene for redigeringsprogrammet.  Det fungerer med en presentasjonsmodell (IDocument) for inndataene, for effektiv visning og manipulering av tekst.

Dette betyr at det må være mulig med tilordning fra en forventet domenemodell (inndata for redigeringsprogrammet) til presentasjonsmodellen.  Tilordningen defineres i en IDocumentProvider.  Når det oppgis inndata for redigeringsprogram, returnerer dokumentleverandøren riktig IDocument.

Java-redigeringsprogrameksempelet arver TextFileDocumentProvider, som er definert av plugin-modulen org.eclipse.ui.editors. Utvidelsen org.eclipse.ui.editors.documentProviders brukes til å definere tilordninger mellom inndatatyper for redigeringsprogram (eller filtyper) og dokumentleverandører. Plugin-modulen for redigeringsprogrammer definerer dokumentleverandøren slik:

   <extension
         point="org.eclipse.ui.editors.documentProviders">
<provider
            class="org.eclipse.ui.editors.text.TextFileDocumentProvider"
            inputTypes="org.eclipse.ui.IStorageEditorInput"
            id="org.eclipse.ui.editors.text.StorageDocumentProvider">
      </provider>
   </extension>

Via dette utvidelsespunktet kan plugin-moduler registrere dokumentleverandører og knytte dem til en filtype eller inndataklasse for redigeringsprogram. Siden Java-redigeringsprogrameksempelet ikke definerer sin egen dokumentleverandørutvidelse, arves den generiske dokumentleverandøren som er angitt for alle inndatatypene som er IStorageEditorInput. Når brukeren åpner en fil for redigering, styrer plattformen opprettelsen av riktig forekomst av dokumentleverandøren. Hvis det er registrert en bestemt dokumentleverandør for filtypen, blir denne leverandøren brukt. Hvis det ikke er oppgitt noen bestemt dokumentleverandør for filtypen, blir inndatatypen for redigeringsprogrammet brukt til å finne riktig leverandør.

Ved å bruke generisk plattformdokumentleverandør, kan Java-redigeringsprogrameksempelet dra nytte av alle funksjonene for dokumentleverandøren, for eksempel filbufring og annen optimalisering.

Dokumentkonfigurering

Hvordan kan et Java-redigeringsprogram som bruker tekstdokumentleverandør for plattform tilby spesialfunksjoner for håndtering av Java-filer?

Utvidelsen org.eclipse.core.filebuffers.documentSetup brukes til å definere tilordninger mellom filtyper og en IDocumentSetupParticipant. Oppsettsdeltakeren konfigurerer dokumentet med eventuelle speisalfunksjoner når det oppgis for redigeringsprogrammet.

<extension
	id="ExampleJavaDocumentSetupParticipant"
	name="%documentSetupParticipantName"
	point="org.eclipse.core.filebuffers.documentSetup">
	<participant
		extensions="jav"
		class="org.eclipse.ui.examples.javaeditor.JavaDocumentSetupParticipant">
	</participant>
   </extension>

Denne utvidelsesdefinisjonen gjør det mulig for eksempelet å konfigurere dokumentet for Java-spesifikke oppgaver. Så hva gjør JavaDocumentSetupParticipant? Vi skal se en forenklet versjon av konfigurasjonsmetoden.

 	public void setup(IDocument document) {
		...
		IDocumentPartitioner partitioner= new FastPartitioner(JavaEditorExamplePlugin.getDefault().getJavaPartitionScanner(), JavaPartitionScanner.JAVA_PARTITION_TYPES);
		partitioner.connect(document);
		...
	}

Denne konfigurasjonskoden konfigurerer et objekt som kalles partisjonerer.

Partisjoner

Partisjonereren (IDocumentPartitioner) deler dokumentet inn i områder, partisjoner, som ikke overlapper hverandre.  Partisjoner (representert av ITypedRegion) er nyttige når ulike deler av dokumentet skal håndteres på forskjellige måter for funksjoner som syntaksutheving eller formatering.

I Java-redigeringsprogrameksempelet er dokumentet delt inn i partisjoner som representerer Javadoc-kommentarene, kommentarer på flere linjer og det øvrige innholdet. Hvert område tildeles en innholdstype og posisjonen denne har i dokumentet. Posisjoner oppdateres etter hvert som brukeren redigerer tekst.

Regelbasert dokumentpartisjonering

Hvert enkelt redigeringsprogram fastsetter hensiktsmessig implementering av en dokumentpartisjonerer.  Det følger med støtte for regelbasert dokumentskanning i org.eclipse.jface.text.rules.  Ved å bruke en regelbasert skanner kan et redigeringsprogram bruke FastPartitioner fra rammeverket.

IDocumentPartitioner partitioner= new FastPartitioner(JavaEditorExamplePlugin.getDefault().getJavaPartitionScanner(), JavaPartitionScanner.JAVA_PARTITION_TYPES);

RuleBasedPartitionScanner er superklassen for regelbaserte skannere. Superklasser oppregner og implementerer reglene som skal brukes for å skille symboler som linjeskilletegn, blanktegn og generiske mønstre fra hverandre ved skanning av et dokument. JavaPartitionScanner i eksempelet nedenfor definerer regler for å skille mellom kommentarer på en linje, tegnkonstanter, Javadoc, kommentarer på flere linjer og ord.  Dette gjøres i skannerens konstruktør:

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);
}

Du finner mer informasjon om hvordan du definerer regler og hvilke type regler som er tilgjengelige, i klassene i org.eclipse.jface.text.rules.  Vi kommer tilbake til skannere når vi ser på syntaksfarger.