Modifications requises lors de l'adoption des API et des mécanismes de la version 3.1

La présente section décrit les modifications à apporter obligatoirement pour que votre plug-in 3.0 adopte les API et les mécanismes de la version 3.1.

Support annuler/rétablir de plateforme

Eclipse 3.1 fournit une nouvelle infrastructure pour définir des opérations annulables et un historique d'opérations partagé qui conserve le suivi des opérations exécutées, annulées et rétablies. Les différents cadre de travail annulés fournis par des plug-ins complémentaires doivent migrer dans le temps vers le support d'opérations de la plateforme, de sorte que les clients de ces cadres de travail puissent les intégrer plus profondément avec la plateforme et rendre disponibles leurs opérations annulables pour une annulation dans d'autres éditeurs et vues de plug-in. Se reporter à la documentation Opérations annulables pour obtenir des informations de base sur l'ajout du support d'annulation à un plug-in. Les plug-ins qui définissent déjà le support d'annulation ou utilisent un autre cadre de travail peuvent être migrés vers le nouveau support d'annulation par étapes, comme décrit ci-dessous.

Migration de classes (commande) d'opérations spécifiques aux plug-ins vers IUndoableOperation

Les plug-ins qui définissent déjà des classes décrivant leurs opérations annulables doivent ajouter une implémentation pour l'interface IUndoableOperation dans leurs classes d'opération/de commande. Les plug-ins peuvent encore utiliser des anciens cadres de travail pour gérer l'historique (pile de commandes) si nécessaire, mais le fait de fournir une interface pour IUndoableOperation permet aux clients d'un plug-in d'utiliser les mêmes opérations dans l'historique des opérations de la plateforme et de mélanger et de faire correspondre les opérations annulables à partir des différents plug-ins. Cette stratégie est similaire à celle utilisée par les éditeurs de texte SDK pour migrer vers le nouveau cadre de travail des opérations. Si un mappage direct de l'interface est impossible, des enveloppeurs peuvent être utilisés pour mapper le protocole IUndoableOperation vers les objets d'annulation patrimoniaux. Cette stratégie est utilisée par le support de réusinage de la plateforme/JDT. La migration des classes d'opération/de commande vers IUndoableOperation est une étape importante car elle permet aux opérations annulables des différents cadres de travail d'être utilisés par d'autres plug-ins sans qu'un plug-in ait besoin de migrer complètement.

Migration des piles de commandes avec IOperationHistory

Une fois que les commandes ou les opérations annulables sont exprimées en termes de IUndoableOperation, les plug-ins qui définissent un historique d'annulation (pile de commandes) pour conserver un suivi des opérations annulables et rétablissables peuvent migrer vers l'historique des opérations de la plateforme en définissant un IUndoContext qui représente leur historique d'annulation. Les historiques d'annulation précédemment gérés localement peuvent être fusionnés dans l'historique des opérations commun en définissant un contexte d'annulation unique pour chaque partie ou pour chaque objet du modèle, en ajoutant le contexte d'annulation approprié à chaque opération, puis en ajoutant l'opération à l'historique des opérations de la plateforme. Les historiques d'annulation avec une étendue plus globale peuvent être implémentés en définissant un contexte d'annulation unique représentant cette étendue d'annulation, en assignant ce contexte à chaque opération et enfin en ajoutant l'opération à l'historique des opérations de la plateforme. Se reporter à la documentation Opérations annulables pour obtenir des exemples de création de contextes d'annulation et d'ajout d'opérations à l'historique des opérations de la plateforme.

Définition des opérations annulables globales vers le plan de travail

Les plug-ins qui veulent que leurs opérations soient annulables depuis les vues du plan de travail, comme le navigateur ou l'explorateur du package, doivent assigner le contexte d'annulation du plan de travail à leurs opérations. Se reporter à la documentation Opérations annulables pour en savoir plus sur ce contexte d'annulation et savoir comment il peut être extrait par des plug-ins sans tête et le plan de travail.

Gestionnaires des actions annuler/rétablir de la plateforme

Les plug-ins qui ne définissent pas d'infrastructure d'annulation ou d'opérations annulables, mais qui veulent fournir un accès à l'historique d'annulation de la plateforme, doivent prendre en compte le reciblage des gestionnaires d'actions d'annulation et de rétablissement globaux avec les nouveaux gestionnaires d'actions d'annulation et de rétablissement communs. Les gestionnaires d'actions doivent avoir un contexte d'annulation spécifiant l'historique d'annulation et de rétablissement à indiquer. Les plug-ins peuvent utiliser leurs contextes d'annulation localement définis pour afficher l'historique d'annulation et de rétablissement en partie local. Le contexte d'annulation du plan de travail peut être utilisé pour indiquer l'historique d'annulation et de rétablissement de la taille du plan de travail. Encore une fois, la documentation Opérations annulables contient un exemple détaillé.

Migration des actions d'opérations textuelles vers les gestionnaires d'actions communs

La migration des actions d'annulation et de rétablissement de l'éditeur de texte est un peu différente du simple reciblage des gestionnaires d'actions d'annulation/de rétablissement globaux. Le cadre de travail AbstractTextEditor définit des actions de texte communes à l'aide d'une TextOperationAction paramétrée. Ces actions sont stockées localement dans le cadre de travail et utilisées pour distribuer diverses commandes vers la cible d'opération de texte d'un éditeur. Pour que l'annulation de texte fonctionne correctement, le cadre de travail de l'éditeur de texte s'appuie sur la présence des actions d'opérations de texte avec les id appropriées (ITextEditorActionConstants.REDO et ITextEditorActionConstants.UNDO).

AbstractTextEditor a été migré de manière à créer les gestionnaires d'actions communs, tout en les assignant au tableau TextOperationAction avec leurs id patrimoniaux. De cette manière, les nouveaux gestionnaires d'action d'annulation et de rétablissement peuvent être extraits à l'aide des techniques patrimoniales pour extraire l'action et effectuer une opération. Les éditeurs de texte de la hiérarchie AbstractTextEditor hériteront de ce comportement.

Les éditeurs qui n'héritent pas de ce comportement de AbstractTextEditor doivent prendre en compte la migration des actions d'annulation et de rétablissement existantes pour utiliser les nouveaux gestionnaires. Les éditeurs ayant des TextOperationActions d'annulation et de rétablissement patrimoniales auront toujours un support d'annulation local qui fonctionne, étant donné que l'API du gestionnaire d'annulation de texte JFace utilisée par ces actions est toujours prise en charge. Cependant, les étiquettes d'actions d'annulation et de rétablissement ne seront pas compatibles avec les nouvelles actions d'annulation/de rétablissement Eclipse SDK, qui affichent le nom de l'opération d'annulation ou de rétablissement disponible. Pour créer les gestionnaires d'actions d'annulation et de rétablissement communs, le contexte d'annulation utilisé par le gestionnaire d'annulation du visualiseur de texte doit être utilisé lors de la création des gestionnaires d'actions et ces gestionnaires doivent être définis dans l'éditeur à l'aide de l'id ITextEditorActionConstants appropriée. Se reporter à AbstractTextEditor.createUndoRedoActions() et AbstractTextEditor.getUndoContext() pour obtenir un exemple détaillé. Les éditeurs qui s'appuient sur une sous-classe EditorActionBarContributor pour s'ajouter aux barres d'action de leurs éditeurs peuvent utiliser une technique similaire en créant des gestionnaires d'actions d'annulation et de rétablissement et en les paramétrant lorsque l'éditeur actif est définit.

Améliorations de l'aide

Recherche d'informations

Les plug-ins qui contribuent aux pages de recherche dans la boîte de dialogue Rechercher doivent prendre en compte le portage de toutes leurs recherches d'informations dans les moteurs de recherche fédérés. Comme dans la version 3.1, toutes les recherches d'informations sont séparées de la recherche d'artefacts du plan de travail. Les moteurs de recherche d'informations sont exécutés parallèlement aux tâches d'arrière-plan et leurs résultats assemblés dans la nouvelle vue Aide. Se reporter à Aide à la recherche pour en savoir plus.

Aide dynamique

La nouvelle vue d'aide dynamique fonctionne avec les ID de contexte existants qui sont statistiquement associés aux widgets dans les boîtes de dialogue et les parties du plan de travail. Cependant, si vous capturez des événements d'aide et affichez l'aide, la vue d'aide dynamique n'affichera rien d'utile. Pour résoudre le problème, vous devez adapter la nouvelle interface IContextProvider, comme décrit dans le document Aide du contexte dynamique.

Magasins de préférences JFace

Comme pour la version 3.1, l'élément org.eclipse.jface.preference.IPreferenceStore qui est renvoyé par AbstractUIPlugin.getPreferenceStore() sera une instance de org.eclipse.ui.preferences.ScopedPreferenceStore. Le ScopedPreferenceStore utilise l'API org.eclipse.core.runtime.preferences pour gérer les préférences. Dans la version 3.0 il utilisait la couche de compatibilité comme interface avec une instance de org.eclipse.core.runtime.Preferences.

Dans la version 3.1 nous avons levé toute ambiguïté concernant IPreferenceStore pour être plus précis sur les types des valeurs envoyées dans les événements de changement de préférences. Le IPreferenceStore de AbstractUIPlugin#getPreferenceStore a le même comportement qu'avant, mais est maintenant défini plus clairement.

Typage : org.eclipse.jface.util.IPropertyChangeListener ajouté à un IPreferenceStore peut recevoir deux types de valeurs anciennes et nouvelles - des représentations avec des types ou des chaînes. Tout événement généré par un appel à une API IPreferenceStore typée (comme setValue (clé de chaîne, valeur booléenne) générera un événement typé. Il est également possible que des événements soient propagés à partir des préférences d'exécution principales, qui génèrent un événement sans type (par exemple sur une importation de préférences). Les programmes d'écoute de propriétés doivent être préparés pour ces deux possibilités. Notez aussi que les événements typés ne seront propageront pas les types primitifs, donc un appel à setValue(clé de chaîne, valeur booléenne) aura pour résultat un événement dont les valeurs anciennes et nouvelles (oldValue et newValue) sont booléennes.

putValue: IPreferenceStore.putValue(clé de chaîne, valeur booléenne) ne générera pas d'événement 'changement'. Cette API est destinée à être utilisée pour des préférences privées, auquel aucun programme d'écoute ne réagira.

initializeDefaultPreferences. Cette API était dépréciée dans Eclipse 3.0 car elle n'est mise en application que si la couche de compatibilité est utilisée. Comme la plupart des plug-ins reposent sur AbstractUIPlugin#getPreferenceStore pour leur magasin de préférences, elle était mise en application sur le plug-in prédédemment démarré. Si votre plug-in n'accède pas à la couche de compatibilité, cette méthode peut ne pas être déclenchée. Il est recommandé de créer un org.eclipse.core.runtime.preferences.AbstractPreferenceInitializer pour traiter l'initialisation des préférences.