Description : ce point d'extension est utilisé pour ajouter de nouvelles actions aux menus en incrustation détenus par d'autres plug-ins. La contribution d'action peut être réalisée pour un type d'objet spécifique (objectContribution) ou pour un menu en incrustation spécifique. Lorsqu'elle est enregistrée pour un type d'objet, la contribution apparaît dans tous les afficheurs où sont sélectionnés des objets du type spécifié. En revanche, l'enregistrement sur un menu en incrustation apparaît uniquement dans le menu spécifié, quelle que soit la sélection.
Lorsque la sélection est hétérogène, la contribution est dans la mesure du possible, appliquée si elle est enregistrée pour un type courant de la sélection. Si une correspondance directe est impossible, la correspondance avec les super classes et les super interfaces est tentée.
La sélection peut être davantage limitée via l'utilisation d'un filtre de nom. Dans ce cas, tous les objets de la sélection doivent correspondre au filtre afin d'appliquer la contribution.
Des actions individuelles dans une contribution d'objet peuvent utiliser un attribut enablesFor pour spécifier s'il ne doit s'appliquer qu'à un seul, à plusieurs ou à tout autre type de sélection.
Si ces mécanismes de filtrage sont inappropriés, une contribution d'action peut utiliser le mécanisme des filtres. Dans ce cas, les attributs de l'objet cible sont décrits dans une série de paires clé-valeur. Les attributs qui s'appliquent à la sélection sont spécifiques au type et surpassent le domaine du plan de travail, aussi ce dernier délègue-t-il le filtrage à ce niveau à la sélection réelle.
Marques de configuration :
<!ELEMENT objectContribution (filter | menu | action)*>
<!ATTLIST objectContribution
id
CDATA #REQUIRED
objectClass CDATA #REQUIRED
nameFilter CDATA #IMPLIED
>
<!ELEMENT action EMPTY>name : nom du séparateur auquel il peut être ultérieurement fait référence en tant que dernier jeton dans le chemin d'accès de l'action. De ce fait, les séparateurs servent de groupes désignés dans lesquels des actions peuvent être ajoutées.
Les libellés d'actions et de menus peuvent contenir des caractères spéciaux qui encodent les mnémoniques et les raccourcis-clavier en respectant les règles suivantes :
L'exemple suivant est celui d'un point d'extension de menu en incrustation :
<extension point="org.eclipse.ui.popupMenus">
<objectContribution
id="com.xyz.C1"
objectClass="org.eclipse.core.resources.IFile"
nameFilter="*.java">
<menu id="com.xyz.xyzMenu"
path="additions"
label="&XYZ Java Tools">
<separator name="group1"/>
</menu>
<action id="com.xyz.runXYZ"
label="&Run XYZ Tool"
menubarPath="com.xyz.xyzMenu/group1"
icon="icons/runXYZ.gif"
helpContextId="com.xyz.run_action_context"
class="com.xyz.actions.XYZToolActionDelegate"
enablesFor="1">
</action>
</objectContribution>
<viewerContribution
id="com.xyz.C2"
targetID="org.eclipse.ui.views.TaskList">
<action
id="com.xyz.showXYZ"
label="&Show XYZ"
menubarPath="additions"
icon="icons/showXYZ.gif"
helpContextId="com.xyz.show_action_context"
class="com.xyz.actions.XYZShowActionDelegate">
</action>
</viewerContribution>
</extension>
Dans l'exemple ci-dessus, l'action spécifiée n'activera qu'une seule sélection (l'attribut enablesFor). De plus, chaque objet de la sélection doit implémenter l'interface spécifiée (IFile) et doit être un fichier Java. Cette action sera ajoutée dans un sous-menu précédemment créé. Cette contribution sera effective dans toute vue comportant la sélection requise.
En revanche, la contribution de l'afficheur ci-dessus n'apparaîtra que dans la vue des tâches et ne sera pas affectée par la sélection effectuée dans la vue.
L'exemple ci-dessous est celui d'un mécanisme de filtrage. Dans ce cas, l'action apparaîtra uniquement pour les IMarkers achevés et dont la priorité est élevée.
<extension point="org.eclipse.ui.popupMenus">
<objectContribution
id="com.xyz.C1"
objectClass="org.eclipse.core.resources.IMarker">
<filter name="done"
value="true"/>
<filter name="priority"
value="2"/>
<action id="com.xyz.runXYZ"
label="High Priority Completed Action Tool"
icon="icons/runXYZ.gif"
class="com.xyz.actions.MarkerActionDelegate">
</action>
</objectContribution>
</extension>
Informations d'API : la valeur de la classe de l'attribut d'action doit être un nom complet qualifié de classe Java qui implémente org.eclipse.ui.IObjectActionDelegate dans le cas de contributions d'objets, org.eclipse.ui.IViewActionDelegate pour les contributions aux afficheurs appartenant aux vues ou org.eclipse.ui.IEditorActionDelegate pour les contributions aux afficheurs appartenant éditeurs. Dans tous les cas, la classe d'implémentation est chargée aussi tard que possible afin d'éviter le chargement du plug-in tout entier avant qu'il ne soit réellement nécessaire.
Remarque : Pour la compatibilité avec les versions antérieures, org.eclipse.ui.IActionDelegate peut être implémenté pour les contributions d'objets.
L'extension d'un menu en incrustation dans un composant est possible uniquement si le composant cible publie un menu pour extension. Cette opération est vivement conseillée car elle améliore l'extensibilité du produit. Pour ce faire, chaque composant doit publier des menus en incrustation définis en appelant IWorkbenchPartSite#registerContextMenu. Une fois ceci fait, le plan de travail insère automatiquement toutes les extensions d'action qui existent.
Un ID menu doit être fourni pour chaque menu enregistré. Pour plus de cohérence entre les composants, la stratégie énoncée ci-après doit être adoptée par toutes les classes d'implémentation de composant.
Un objet du plan de travail qui est la sélection dans un menu contextuel peut définir un org.eclipse.ui.IActionFilter. Il s'agit d'une stratégie de filtrage qui peut effectuer des filtrages spécifiques au type. Le plan de travail extrait le filtre pour la sélection en testant pour voir s'il implémente IActionFilter. Si l'opération échoue, le plan de travail demandera un filtre via le mécanisme IAdaptable.
Implémentation fournie : la vue du plan de travail comporte des menus en incrustation intégrés qui sont déjà chargés pour un certain nombre d'actions. Les plug-ins peuvent contribuer à ces menus. Si un afficheur a réservé des emplacements pour ces contributions et qu'ils sont rendus publics, les noms des emplacements peuvent être utilisés comme chemins d'accès. Sinon, les actions et les sous-menus seront ajoutés à la fin du menu en incrustation.