Exemple - Editeur Java

Introduction

L'exemple Editeur Java fait la démonstration des fonctions standard disponibles pour les éditeurs de texte personnalisés.  Il montre également comment associer un éditeur particulier à une extension de fichier (dans cet exemple, l'extension .jav) et comment définir un fournisseur de documents personnalisé à utiliser par cet éditeur. Cet exemple est seulement fourni à des fins de démonstration. Le véritable support d'édition Java est assuré par le JDT (Java Development Tooling) de la plate-forme Eclipse.

Le code pour cet exemple se trouve dans le plug-in org.eclipse.ui.examples.javaeditor. Pour explorer le code, il est recommandé d'importer ce plug-in dans votre espace de travail.

Fonctions illustrées dans l'exemple d'éditeur

Fonctions non illustrées

Exécution de l'exemple d'éditeur Java

  1. Créez un projet.
  2. Créez un fichier portant l'extension ".jav" dans le nouveau projet. L'exemple d'éditeur Java s'ouvre automatiquement.
  3. Insérez du code Java. Celui-ci est colorié dynamiquement. Dans l'exemple d'éditeur, les éléments de langage suivants sont présentés avec des couleurs différentes : commentaires multilignes, commentaires monolignes, mots réservés du langage Java, constantes chaîne et caractère, code Java normal et commentaires multilignes faisant suite aux instructions Javadoc. A l'intérieur de ces commentaires Javadoc, les mots clés et les balises Javadoc sont coloriés différemment (vert pour les mots clés et gris pour les balises).
  4. Ouvrez un nouveau commentaire Java multiligne en insérant un délimiteur "/*" en dehors de tout commentaire Java existant. La couleur rouge est alors appliquée à tout le texte situé entre le délimiteur "/*" inséré et la première occurrence du délimiteur "*/" ou la fin du texte proprement dit. Ajoutez une autre marque "*". La partie en rouge devient noire, car le commentaire multiligne normal est maintenant considéré comme contenant un commentaire Javadoc. Appelez la fonction d'aide à la saisie de code (c'est-à-dire l'assistant de contenu) en appuyant sur CTRL-ESPACE. Le rôle de cette fonction est d'aider l'utilisateur à écrire son code. Elle affiche la liste de toutes les propositions qui peuvent servir à compléter le code à partir de l'endroit où elle est appelée. A l'intérieur d'un commentaire Javadoc, l'exemple d'éditeur propose toujours tous les mots clés Javadoc.
  5. Placez-vous en dehors de tout commentaire Java et appelez les suggestions de contenu en appuyant sur CTRL+MAJ+ESPACE. Cinq propositions vous sont faites. Sélectionnez-en une et appuyez sur Entrée. Une petite fenêtre flottante rouge apparaît au-dessus de la ligne en cours, affichant la proposition sélectionnée. Les suggestions de contenu permettent à l'utilisateur d'exprimer son intention (par exemple en entrant un appel de méthode), et elles l'aident lors de cette opération en lui fournissant des informations contextuelles. Dans l'exemple d'éditeur, la proposition est considérée valide cinq caractères avant ou après le point d'appel initial. La suggestion de contenu étant toujours visible, appelez l'assistant de contenu en appuyant sur CTRL+ESPACE. Appelé dans ces conditions, l'assistant de contenu doit aider l'utilisateur à exécuter l'intention exprimée, qui est toujours visible dans la suggestion de contenu. A l'intérieur d'un code Java normal, l'exemple d'éditeur propose toujours tous les mots clés Java.
  6. Sauvegardez le code Java. La sauvegarde met à jour le décomposeur de contenu. Ce dernier contient dix entrées, chacune représentant un segment du code Java affiché dans l'éditeur (les dix segments ont la même taille). Ce style de décomposition du contenu a été choisi pour montrer que la sémantique des plages mises en évidence peut être définie arbitrairement. (Voir les étapes suivantes.)
  7. Sélectionnez l'une des entrées dans le décomposeur de contenu. Les lignes correspondantes sont repérées par une barre bleue dans la règle verticale gauche de l'éditeur.
  8. Activez maintenant le mode de présentation segmentée de l'éditeur Java. Pour cela, assurez-vous que l'éditeur est la fenêtre active, puis cliquez sur le bouton de la barre d'outils du bureau dont l'info-bulle est "Enable/Disable segmented source viewer".  Cette fonction est utilisée pour l'affichage isolé de méthodes et autres emplois similaires.
  9. Sélectionnez une entrée différente dans le décomposeur de contenu. Maintenant, seul le segment sélectionné est affiché dans l'éditeur. En désélectionnant l'entrée dans le décomposeur de contenu, vous voyez réapparaître l'intégralité du code Java.
  10. Sélectionnez une entrée dans le décomposeur de contenu, puis sélectionnez une fraction du texte visible et ajoutez une tâche pour cette sélection. La tâche apparaît dans la liste des tâches. Modifiez la fraction de code visible. Dans la liste des tâches, sélectionnez la tâche précédemment créée et cliquez sur le bouton "Go to file" (Accéder au fichier). La tâche est sélectionnée dans la portion visible et elle prend en compte les modifications précédemment appliquées.
  11. Sélectionnez une autre entrée dans le décomposeur de contenu. Révélez la tâche précédemment ajoutée à partir de la liste des tâches. La plage de mise en évidence de l'éditeur s'agrandit automatiquement pour englober la plage de la tâche révélée.
  12. Ouvrez un nouvel espace de travail. Dans ce nouvel espace, ouvrez un éditeur Java sur le fichier que vous avez créé dans l'espace initial. Modifiez le contenu de l'éditeur. Retournez à l'espace de travail initial. L'éditeur montre les modifications apportées au fichier dans l'autre espace de travail. Les deux éditeurs ouverts sur le même fichier sont liés.

Principes de création d'éditeurs de texte personnalisés

Les étapes suivantes sont généralement nécessaires pour développer un éditeur de texte personnalisé.
  1. Créez un fournisseur de documents. Un fournisseur de documents (voir IDocumentProvider) produit et gère des documents (voir IDocument) qui contiennent une représentation texte des éléments d'entrée de l'éditeur. Il est important de déterminer le mode d'exécution de la traduction entre un élément et sa représentation texte et de décider si le fournisseur de documents doit être partagé ou non par plusieurs éditeurs. Pour plus de détails, voir la classe FileDocumentProvider dans l'exemple d'éditeur Java.
  2. Créez un partitionneur de document. Un partitionneur de document (voir IDocumentPartitioner) divise un document en régions disjointes. Il affecte à chaque région un type de contenu choisi parmi un ensemble de types de contenus qu'il prédéfinit. Chaque fois qu'un document est modifié, son partitionnement doit être mis à jour. Pour plus de détails, voir la classe JavaPartitioner dans l'exemple d'éditeur Java. Le JavaPartitioner détermine des régions de types "commentaires multilignes", "commentaires Javadoc" et "autres éléments". Vous devez vous assurer qu'un partitionneur de document est défini pour chaque document produit par le fournisseur de documents.
  3. Déterminez lequel des plug-ins d'afficheur de code source doit être fourni. Parmi les plug-ins supportés figurent les stratégies de retrait automatique, les stratégies de double clic, le formateur de contenu et le réconciliateur (ou synchroniseur) de présentation de texte. La description qui suit se limitera au réconciliateur de présentation de texte (voir IPresentationReconciler). Dans l'exemple d'éditeur Java, le réconciliateur de présentation de texte est utilisé pour implémenter la mise en évidence de syntaxe.
  4. Créez, pour tous les plug-ins d'afficheur de code source, les extensions appropriées à chaque type de contenu supporté. Comme nous l'avons vu plus haut, c'est le partitionneur de document qui définit les types de contenus supportés. L'implémentation par défaut de IPresentationReconciler supporte IPresentationDamagers et IPresentationRepairers comme extensions. Ces extensions sont considérées comme spécifiques à un type de contenu particulier. Par conséquent, pour un éditeur personnalisé, vous devez d'abord sélectionner un sous-ensemble des types de contenus supportés. Les régions d'un type faisant partie du sous-ensemble sélectionné seront soumises à la mise en évidence de syntaxe. Pour chacun de ces types, les extensions doivent être implémentées. Voir les classes JavaDamagerRepairer et JavaDocDamagerRepairer dans l'exemple d'éditeur.
  5. Générez une configuration d'afficheur de code source en utilisant les plug-ins et les extensions précédemment créés. Voir la classe JavaSourceViewerConfiguration dans l'exemple d'éditeur.
  6. Personnalisez la classe TextEditor ou AbstractTextEditor avec le partitionneur de document et la configuration d'afficheur de code source. Ajoutez ou remplacez des actions à votre gré et adaptez la construction du menu contextuel de l'éditeur. Dans la version actuelle, cette personnalisation doit être réalisée dans une sous-classe. Voir la classe JavaEditor dans l'exemple d'éditeur.
  7. Configurez un contributeur de barre d'actions, dont le rôle est d'ajouter les actions en rapport avec l'éditeur à la barre d'outils et aux menus du bureau. Voir la classe JavaActionContributor dans l'exemple d'éditeur.
  8. Etendez le fichier de configuration XML du plug-in de l'éditeur afin que ce dernier s'enregistre au point d'extension prédéfini pour un ensemble spécifique d'extensions de fichier. Configurez également le contributeur de barre d'actions dans le fichier XML. Voir le fichier plugin.xml de cet exemple.

Organisation du code de l'exemple

Le code de l'exemple d'éditeur Java est organisé en quatre packages :