Exemple - Outil Readme
Introduction
L'éditeur Readme montre comment définir des points d'extension à utiliser
par d'autres plug-in. Il montre également comment créer des extensions (nouvelles entrées) dans les menus contextuels
des ressources, de nouveaux assistants de ressources, un éditeur pour une extension de fichier particulière (.readme),
une vue personnalisée et des pages de propriétés.
Exécution de l'exemple
Pour commencer à utiliser cet exemple, créez un fichier avec l'extension .readme en utilisant
l'assistant de création de fichier ou l'assistant de création d'exemples.
Vous pouvez afficher la vue supplémentaire fournie par cet exemple en sélectionnant
Window > Afficher la vue > Autre, puis en développant la section Readme. Vous pouvez observer l'action
de cette vue en cliquant sur l'icône readme de la vue Navigateur.
Création d'un nouveau fichier readme
Créez un fichier .readme. Pour cela, sélectionnez Nouveau dans le menu Fichier, puis
Autre... dans le sous-menu. Dans l'assistant, cliquez sur l'option Simple, puis
choisissez Fichier dans la liste située à gauche. Cliquez sur Suivant pour indiquer
le nom du fichier (veillez à lui associer l'extension .readme) et le dossier dans lequel il
doit être placé.
Exemples d'assistants de création
Dans le menu Fichier, sélectionnez Nouveau, puis Exemple... dans le sous-menu.
Sélectionnez ensuite Exemples d'assistants de création. Sélectionnez
Fichier Readme. Cliquez sur Suivant (Next). Sélectionnez le dossier
dans lequel vous souhaitez que le fichier soit créé. Tapez le nom du fichier en lui associant
l'extension .readme. Cliquez sur Fin (Finish).
Action d'extension de la vue Readme
Dans la vue Navigateur, sélectionnez un fichier dont l'extension est .readme. S'il n'y en a aucun,
créez-en un. La barre d'outils locale de la vue Navigateur comporte un bouton
dont l'info-bulle est "Run Readme View Extension". Cliquez sur ce bouton. Une boîte de dialogue
s'affiche en incrustation, avec le message "View Action executed".
Menus contextuels (ou en incrustation)
Dans la vue Navigateur, sélectionnez un fichier dont l'extension est .readme.
S'il n'y en a pas, créez-en un. Sélectionnez le fichier et ouvrez son menu contextuel.
Notez que le menu comporte une option intitulée "Show Readme Action". Sélectionnez
cette option. Vous obtenez une boîte de dialogue dans laquelle s'affiche le message
"Popup Menu Action Executed".
Page de préférences
Dans le menu Fenêtre, sélectionnez Préférences. Cliquez sur la page intitulée
Exemple Readme (Readme Example). Il s'agit d'un exemple de page de préférences.
Page de propriétés
Dans la vue Navigateur, sélectionnez un fichier dont l'extension est .readme.
S'il n'y en a pas, créez-en un. Sélectionnez le fichier et ouvrez son menu contextuel.
Dans ce menu, sélectionnez l'option Propriétés (Properties). Cliquez ensuite sur la page
intitulée Outil Readme (Readme Tool) pour voir un exemple de page de propriétés.
Editeur de fichier readme
L'éditeur de fichier readme (Readme File Editor) est utilisé par défaut pour
tous les fichiers dont l'extension est .readme.
Créez un fichier avec cette extension et ouvrez-le en cliquant deux fois dessus
ou en affichant son menu contextuel, puis en sélectionnant Ouvrir avec > Readme File
Editor. Notez que l'éditeur possède une icône représentant un crayon. C'est cet éditeur
que l'outil Readme utilise par défaut pour les fichiers dont l'extension est .readme.
Actions de l'éditeur de fichier readme
Ces actions sont applicables uniquement à un éditeur particulier.
Lorsque la fenêtre active est celle d'un éditeur de fichier readme, la barre d'outils
comporte quatre boutons supplémentaires, dont les intitulés (info-bulles) sont
"Run Readme Editor Extension", "Readme Editor Action 1",
"Readme Editor Action 2" et "Readme Editor Action 3".
Un menu intitulé Readme apparaît lorsque la fenêtre active est un éditeur de fichier
readme. Ce menu contient les actions précédemment décrites :
"Readme Editor Action 1", "Readme Editor Action 2" et "Readme Editor Action 3".
Vue Readme Sections
Pour afficher cette vue, sélectionnez Afficher la vue dans le menu
Fenêtre, puis choisissez Autre dans le sous-menu.
Développez la branche Readme, puis sélectionnez Readme Sections. Vous
obtenez la liste des sections du fichier .readme actuellement
sélectionné dans la vue Navigateur. Vous pouvez également voir
la structure d'un fichier .readme dans la vue Structure.
Un fichier dont l'extension est .readme peut être décomposé en sections lorsque ces
sections commencent chacune par un numéro.
Par exemple, si le texte ci-après a été entré dans l'éditeur de fichier readme, l'outil Readme
identifiera deux sections. Pour voir comment les sections sont détectées par cet outil,
tapez du texte dans l'éditeur de fichier readme, puis sauvegardez le fichier à l'aide de la
combinaison de touches CTRL-S ou en sélectionnant Fichier -> Sauvegarder. Ouvrez la vue
Readme Sections et sélectionnez le fichier .readme dans la vue Navigateur.
Exemple de texte :
99.1 Ceci est ma première section
Et voici le texte de ma première section.
99.1.1 Ceci est une sous-section
Et voici le texte de la sous-section.
Glisser-déposer
Vous pouvez observer le comportement de la fonctionnalité de glisser-déposer en sélectionnant
une section dans la vue Structure et en la déposant sur un fichier texte. Le contenu de la partie
sélectionnée est alors ajouté au fichier.
Contribution d'aide
L'exemple Outil Readme montre également comment utiliser et implémenter une aide contextuelle
sur toutes les extensions qu'il fournit, à savoir une vue, diverses actions et une page
d'assistant. Pour obtenir l'aide contextuelle d'une action, passez le pointeur de la souris
sur l'option de menu correspondante, mais ne cliquez pas dessus ; appuyez sur la touche F1.
Vous pouvez aussi obtenir l'aide contextuelle (F1) dans la vue Readme Sections ainsi que sur la
page Example Creation Wizards (dans l'assistant Nouveau).
Détails
L'exemple Outil Readme déclare un seul point d'extension et fournit un certain nombre
d'extensions qui sont très utiles à la compréhension du principe
de fonctionnement du plan de travail ; elles exploitent en effet certains des points d'extension les plus
intéressants parmi ceux que déclare le plan de travail. Les extensions fournies dans cet exemple se composent
de vues et d'actions de vue, de pages de préférences, de pages de propriétés, d'assistants, d'éditeurs et
d'actions d'éditeur, de menus contextuels, de jeux d'actions, de contributions d'aide, de contextes
d'aide et d'actions de glisser-déposer.
Cet exemple fournit également un point d'extension déclaré dans le plug-in.
La classe IReadmeFileParser est requise pour tout plug-in qui utilise
l'extension org.eclipse.ui.examples.readmetool.sectionParser définie
par cet exemple. La classe DefaultSectionParser est un exemple
d'implémentation de IReadmeFileParser.
La classe ReadmeEditor, qui implémente IEditorPart, est définie comme éditeur des fichiers
dont l'extension est .readme dans le manifeste plugin.xml du plug-in qui utilise
le point d'extension org.eclipse.ui.editors. La classe ReadmeSectionsView implémente IViewPart et
est définie comme vue utilisant le point d'extension
org.eclipse.ui.views. Ce point d'extension définit également une catégorie pour la vue,
catégorie qui est réservée à l'usage de la fonction de sélection de vue.
Deux types de préférences sont définis dans cet exemple, les préférences du
plan de travail et les propriétés de ressource. Les préférences du plan de travail sont définies dans la classe
ReadmePreferencePage, qui implémente IWorkbenchPreferencePage. La page de préférences résultante sera donc ajoutée à la
boîte de dialogue Fenêtre->Préférences. La classe
est définie dans le point d'extension org.eclipse.ui.preferencePages, dans le fichier manifeste
plugin.xml. Les deux pages de propriétés de ressource sont représentées par les
classes ReadmeFilePropertyPage
et ReadmeFilePropertyPage2, l'une et l'autre implémentant l'interface IWorkbenchPropertyPage.
Elles sont toutes deux définies pour être appelées sur le type IFile par la balise
objectClass du fichier plugin.xml, dans le point d'extension org.eclipse.ui.propertyPages.
La classe ReadmeCreationWizard, qui implémente INewWizard, est définie dans le
point d'extension org.eclipse.ui.newWizards, dans le fichier plugin.xml. Ce point d'extension
définit également la catégorie de l'assistant qui s'affiche lorsque l'utilisateur
sélectionne Fichier -> Nouveau ->Exemple....
Plusieurs raccords (stubs) d'actions sont ajoutés à cet exemple. Le jeu d'actions
déclare un menu intitulé Readme File Editor, à inclure dans la barre de menus de la fenêtre
du plan de travail au moyen du point d'extension
org.eclipse.ui.actionSets. Il définit également, par les balises toolbarPath et menubarPath,
une action à inclure dans la barre d'outils et dans la barre de menus du plan de
travail. Il utilise la classe WindowActionDelegate, qui implémente
IWorkbenchWindowActionDelegate, pour implémenter l'action.
L'action à insérer dans le menu contextuel est définie comme objectContribution par la
classe PopupMenuActionDelegate, dans le point d'extension org.eclipse.ui.popupMenus.
PopupMenuActionDelegate implémente IObjectActionDelegate et utilise l'objet IWorkbenchPart
fourni pour ouvrir une boîte de message. L'action de vue ViewActionDelegate est
définie dans le point d'extension org.eclipse.ui.viewActions et implémente
IViewActionDelegate. La vue dans laquelle elle apparaît est définie par la balise
targetID. Dans cet exemple, il s'agit de
org.eclipse.ui.views.ResourceNavigator. L'action d'éditeur est définie
par la classe EditorActionDelegate, qui implémente IEditorActionDelegate.
Elle est ajoutée au moyen du point d'extension org.eclipse.ui.editorActions. L'éditeur
auquel elle est appliquée est défini par la balise targetID. Dans cet exemple, il
s'agit de l'éditeur défini dans org.eclipse.ui.examples.readmetool.ReadmeEditor.
La classe
ReadmeDropActionDelegate implémente IDropDelegate. Les objets IDropDelegate sont
informés chaque fois qu'une action de glisser-déposer est effectuée dans le
plan de travail. Le point d'extension utilisé pour cette action
est org.eclipse.ui.dropActions.