Exemple - outil Readme

Introduction

L'éditeur Readme montre comment définir vos propres points d'extension pour d'autres plug-ins. Il montre aussi comment créer des extensions pour les entrées du menu d'incrustation ressources, de nouveaux assistants ressources, des éditeurs de fichier sur une extension (.readme), des pages de propriétés et une vue personnalisée.

Exécution de l'exemple

Pour commencer à utiliser cet exemple, créez un fichier avec l'extension .readme à l'aide de l'assistant de création de fichiers ou de l'assistant de création d'exemple. La vue supplémentaire  fournie par cet exemple peut être visualisée en sélectionnant Fenêtre > Afficher la vue > Autre et en développant la section Readme. L'action de la vue peut être visualisée en cliquant sur l'icône readme de la vue Navigateur.

Création d'un nouveau fichier readme

Créez un nouveau fichier avec l'extension .readme.  Dans le menu Fichier, sélectionnez Nouveau puis Autre... dans le sous menu.  Cliquez sur Simple dans l'assistant, puis sélectionnez Fichier dans la liste de gauche.  Cliquez sur Suivant pour indiquer un nom de fichier (avec l'extension .readme) et le répertoire qui le contiendra.

Assistant création d'exemple

Dans le menu Fichier, sélectionnez Nouveau, et dans le sous-menu, Exemple...  Puis sélectionnez Assistant création d'exemple. Sélectionnez Fichier Readme. Cliquez sur Suivant. Sélectionnez le dossier dans lequel vous voulez créer le fichier. Saisissez le nom du fichier avec une extension .readme. Cliquez sur Terminer.

Action extension de la vue Readme

Dans la vue Navigateur, sélectionnez le fichier .readme. S'il n'y en a pas, créez-en un. Sur la barre d'outils locale de la vue Navigateur, vous trouverez un bouton dont la bulle d'aide indique Extension de la vue Readme d'exécution. Cliquez sur ce bouton. Une boîte de dialogue annonçant 'Action de la vue exécutée' apparaîtra alors.

Menus d'incrustation

Dans la vue Navigateur, sélectionnez le fichier .readme.  S'il n'y en a pas, créez-en un.  Sélectionnez le fichier pour faire apparaître le menu d'incrustation.  Notez qu'un élément du menu indique Afficher les actions Readme. Choisissez cet élément pour ouvrir une boîte de dialogue 'Action du menu d'incrustation exécutée'.

Page de préférences

Dans le menu Fenêtre, choisissez Préférences. Cliquez sur la page appelée Exemple Readme. Un exemple de page de préférences apparaîtra alors.

Page de propriétés

Dans la vue Navigateur, sélectionnez le fichier .readme.  S'il n'y en a pas, créez-en un. Sélectionnez le fichier pour faire apparaître le menu d'incrustation, puis l'élément Propriétés du menu. Cliquez sur la page appelée Outils Readme pour voir un exemple de page de propriétés.

Editeur de fichiers Readme

L'éditeur de fichiers Readme est l'éditeur par défaut des fichiers *.readme.  Créez un fichier .readme et ouvrez-le en double-cliquant dessus ou en appelant le menu d'incrustation, en sélectionnant Ouvrir avec, puis Editeur de fichiers Readme dans le sous-menu. L'icône de l'éditeur comporte un crayon. Il s'agit de l'éditeur que l'outil readme utilise par défaut pour les fichiers du type *.readme.

Actions de l'éditeur Readme

Voici un exemple d'actions qui ne sont applicables qu'à un éditeur précis. Quand un éditeur de fichiers readme à le focus, notez 4 bouton supplémentaires dans le barre d'outils - Extension éditeur Readme d'exécution, Action éditeur Readme 1, Action éditeur Readme 2, Action éditeur Readme 3.

Un menu déroulant intitulé Readme apparaît quand un éditeur de fichiers readme à le focus. Il contient les actions décrites ci-dessus : Action éditeur Readme 1, Action éditeur Readme 2, Action éditeur Readme 3.

Vue sections Readme

Pour afficher cette vue sections Readme, sélectionner Afficher une vue dans le menu Fenêtre, puis sélectionner Autre... dans le sous-menu.  Développer l'élément Readme et sélectionner Sections Readme. Une liste des sections du fichier *.readme s'affichera quand un fichier .readme est sélectionné dans la vue Navigateur. Vous pouvez également voir la structure d'un fichier *.readme dans la vue Structure.

Un fichier .readme peut être décomposé en sections quand chaque section commence par un chiffre. Par exemple, si le texte suivant était entré dans l'éditeur de fichiers readme, l'outil readme détecterait 2 sections. Pour voir comment les sections sont détectées dans l'outil readme, saisissez du texte dans l'éditeur de fichiers readme, enregistrez le fichier en tapant CTRL-S ou en sélectionnant  Fichier->Enregistrer. Ouvrez la vue Sections Readme et sélectionnez le fichier .readme dans la vue Navigateur.

Exemple de texte :

99.1 Voici ma première section
Ceci est le texte de ma première section.

99.1.1 Voici une sous-section
Ceci est le texte de ma sous-section.

Glisser-déposer

La fonctionnalité glisser-déposer peut être visualisée en sélectionnant une section dans la vue Structure et en déplaçant la sélection sur un fichier texte. Le contenu de la sélection sera ajouté à ce fichier.

Contribution aide

L'exemple de l'outil readme montre également comment utiliser et implémenter l'aide contextuelle dans toutes les extensions qu'il fournit - une vue, diverses actions et une page assistant.Pour obtenir l'aide contextuelle sur une action, passez la souris sur l'élément de menu sans le sélectionner, puis appuyez sur la touche F1.Vous pouvez également obtenir une aide contextuelle (F1) sur la vue Sections Readme et la page Assistant de création d'exemples (dans le nouvel assistant).
 

Détails

L'exemple outils Readme déclare un point d'extension et fournit plusieurs extensions.Les extensions fournies sont assez complètes dans leur compréhension des fonctions du plan de travail, car elles utilisent plusieurs des points d'extension les plus intéressants déclarés par le plan de travail. Les extensions fournies comprises dans cet exemple sont des vues et des actions de vues, des pages de préférences et de propriétés, des assistants, des éditeurs et des actions d'éditeurs, des menus d'incrustation, des jeux d'actions, des contributions et des contextes d'aide, et des actions de déplacement.

Cet exemple fournit également un point d'extension déclaré dans le plug-in. Le IReadmeFileParser de classe est nécessaire pour tout plug-in utilisant l'extension org.eclipse.ui.examples.readmetool.sectionParser que cet exemple définit. La classe DefaultSectionParser est un exemple d'implémentation de IReadmeFileParser.

La classe ReadmeEditor implémente IEditorPart et est définit en tant qu'éditeur dans les fichiers .readme du plugin.xml qui utilise le point d'extension org.eclipse.ui.editors. La classe ReadmeSectionsView implémente IViewPart et est défini comme une vue utilisant le point d'extension org.eclipse.ui.views. Ce point d'extension définit également une catégorie de vue destinée à la sélection de la vue.

Deux types de paramètres de préférences sont définis dans cet exemple, les préférences du plan de travail et les propriétés ressources. Les préférences du plan de travail sont définies dans la classe ReadmePreferencePage qui implémente IWorkbenchPreferencePage afin qu'elles soient ajoutées à 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 plugin.xml. Les deux pages propriétés ressources sont ReadmeFilePropertyPage et ReadmeFilePropertyPage2, et implémentent toutes deux IWorkbenchPropertyPage. Elles sont toutes les deux définies pour être appelées sur le type IFile par la balise objectClass, dans plugin.xml, dans le point d'extension org.eclipse.ui.propertyPages.

La classe ReadmeCreationWizard implémente INewWizard et est définie dans le point d'extension org.eclipse.ui.newWizards, dans plugin.xml. Ce point d'extension définit également la catégorie de l'assistant qui est affiché quand l'utilisateur sélectionne Fichier->Nouveau->Exemple....

Plusieurs modules de remplacement d'action sont ajoutés à cet exemple. Le jeu d'actions déclare un menu étiqueté Editeur de fichiers Readme qui doit être inclus dans la barre de menu de la fenêtre du plan de travail en utilisant le point d'extension org.eclipse.ui.actionSets. Il définit également une action pour les barres d'outil et de menu du plan de travail en utilisant les balises toolbarPath et menubarPath. Il utilise la classe WindowActionDelegate qui implémente IWorkbenchWindowActionDelegate pour implémenter l'action. L'action du menu d'incrustation est définie comme un objectContribution par la classe PopupMenuActionDelegate dans le point d'extension org.eclipse.ui.popupMenus. PopupMenuActionDelegate implémente IObjectActionDelegate et utilise le IWorkbenchPart fourni pour ouvrir une boîte de dialogue. La vue action ViewActionDelegate est définie dans le point d'extension org.eclipse.ui.viewActions et implémente IViewActionDelegate. La vue dans laquelle il apparaît est définie par la balise targetID qui, dans cet exemple, est org.eclipse.ui.views.ResourceNavigator. L'action de l'éditeur est définie par la classe EditorActionDelegate qui implémente IEditorActionDelegate et est ajoutée en utilisant le point d'extension org.eclipse.ui.editorActions. L'éditeur auquel elle est appliquée est défini par la balise targetID qui, dans cet exemple, est définie dans org.eclipse.ui.examples.readmetool.ReadmeEditor.

La classe ReadmeDropActionDelegate implémente IDropDelegate. IDropDelegates sont informés chaque fois qu'une action d'abandon est réalisée dans le plan de travail. Le point d'extension pour cette action est org.eclipse.ui.dropActions.