Documents et partitions

La structure de texte de la plateforme définit un modèle de document pour le texte et fournit un afficheur qui affiche le texte en utilisant ce modèle. Nous commencerons par observer comment l'exemple d'éditeur Java utilise ce modèle.  Nous n'insisterons pas sur les mécanismes de base d'enregistrement d'une extension d'éditeur, puisque ce sujet a déjà été abordé dans la section relative à org.eclipse.ui.editors.   En revanche, nous analyserons les spécificités liées à l'implémentation de la classe d'éditeur dans l'exemple.

Fournisseurs de documents et documents

Dans le plan de travail, un éditeur s'ouvre généralement lorsque l'utilisateur sélectionne un élément de domaine (tel qu'un fichier ou un élément stocké dans un fichier d'archive) et l'ouvre.  Une fois l'éditeur créé, il est associé à une entrée d'éditeur (IEditorInput), qui décrit l'objet édité.

L'exemple d'éditeur Java s'ouvre lorsque l'utilisateur ouvre un fichier ayant l'extension "*.jav".  Auquel cas, l'entrée dans l'éditeur est IFileEditorInput.   La structure de texte de la plateforme est peu concernée par l'entrée d'éditeur elle-même.  Elle travaille avec un modèle de présentation appelé IDocument, pour l'entrée de façon à pouvoir effectivement afficher et manipuler du texte.

Cela signifie qu'il doit exister un moyen de mapper un modèle de domaine donné (l'entrée d'éditeur) à un modèle de présentation.  Ce mappage est défini dans un IDocumentProvider.   Pour une entrée d'éditeur donnée, le fournisseur de documents renvoie un IDocument approprié.

L'exemple d'éditeur Java définit un JavaDocumentProvider qui renvoie le document approprié.  Comment la relation entre le fournisseur de documents approprié et l'extension "*.jav" est-elle établie ? Cette relation est établie dans une extension org.eclipse.ui.documentProviders.   Cette extension est utilisée pour établir des mappages entre des types de fichiers et des fournisseurs de documents.  L'exemple définit son fournisseur de documents comme suit :

<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>

Lorsque l'utilisateur ouvre un fichier ayant l'extension indiquée, le plan de travail gère les détails de création de l'instance de fournisseur de documents.  Le plan de travail ne crée qu'une instance de fournisseur de documents qu'il partage entre les différents éditeurs.

Votre plug-in n'a pas à utiliser ce point d'extension pour enregistrer son fournisseur de documents. Vous pouvez également associer un fournisseur de documents à un éditeur en laissant votre plug-in gérer lui-même le fournisseur de documents.  Cette opération s'effectue généralement dans la classe du plug-in.  Lorsqu'un élément d'entrée est défini dans l'éditeur, ce dernier demande à sa classe de plug-in le fournisseur de documents approprié.  Le plug-in peut gérer la création et les références au fournisseur de documents.  Cette technique est souvent préférable lorsqu'une initialisation spéciale ou un autre processus est impliqué avec le fournisseur de documents.  Vous trouverez un exemple dans ClassFileEditor du JDT. 

Une fois le fournisseur de documents approprié associé à un éditeur, sa principale tâche consiste à créer un document à partir de l'entrée d'éditeur et à configurer un objet approprié pour diviser le document en partitions.  

Partitions

Observons les documents et les partitions dans JavaDocumentProvider.  Lorsqu'un document est créé, un IDocumentPartitioner est créé et défini dans le document.  

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

Le partitionneur est chargé de diviser le document en régions qui ne se chevauchent pas appelées partitions.  Les partitions (représentées dans ITypedRegion) permettent de traiter différemment différentes sections du document en tenant compte de fonctions telles que le formatage ou la mise en évidence de syntaxe.

Dans le cas de l'exemple d'éditeur Java, le document est divisé en partitions qui correspondent aux commentaires javadoc, aux commentaires multilignes et à d'autres éléments.  A chaque région est affecté un type de contenu et sa position dans le document.  Les positions sont actualisées à mesure que l'utilisateur modifie le texte.   

Partitionnement de document de base de règles

Chaque éditeur détermine l'implémentation appropriée d'un partitionneur de document.  L'analyse des documents de base de règles est prise en charge dans org.eclipse.jface.text.rules.   L'emploi d'un scanneur de base de règles permet à un éditeur d'utiliser le DefaultPartitioner fournit pas la structure.

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

RuleBasedPartitionScanner est la superclasse des scanneurs de base de règles.  Les sous-classes sont chargées de l'énumération et de l'implémentation des règles à utiliser pour différencier des jetons tels que les délimiteurs de lignes, les caractères blancs et les motifs génériques lors du scannage d'un document.  Le JavaPartitionScanner de l'exemple définit des règles afin de différencier les commentaires monolignes, les constantes de type caractère, les commentaires javadoc, les commentaires multilignes et les mots.  Cette opération s'effectue dans le constructeur du scanneur :

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

	List rules= new ArrayList();
	// Ajouter une règle pour les commentaires monolignes.
	rules.add(new EndOfLineRule("//", Token.UNDEFINED));

	// Ajouter une règle pour les constantes de type chaîne et caractère.
	rules.add(new SingleLineRule("\"", "\"",
Token.UNDEFINED, '\\'));
	rules.add(new SingleLineRule("'", "'",
Token.UNDEFINED, '\\'));

	// Ajouter une règle pour les mots spéciaux.
	rules.add(new WordPredicateRule(comment));

	// Ajouter des règles pour les commentaires multilignes et 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);
}

Reportez-vous aux classes de org.eclipse.jface.text.rules pour plus de détails sur la définition des règles et sur les types de règles disponibles.  Nous reviendrons sur les scanneurs lorsque nous étudierons la coloration de syntaxe.

Modèles d'annotation

Outre un document approprié, le fournisseur de documents doit aussi fournir un IAnnotationModel approprié à utiliser avec une entrée d'éditeur.  Ce modèle permet de gérer les annotations associées aux documents.  Si vous laissez le fournisseur de documents fournir le modèle, votre éditeur peut utiliser un modèle approprié au type de contenu.  Nous observerons plus en détail les annotations et la façon dont elle sont présentées dans la section suivante.

Copyright IBM Corporation and others 2000, 2003.