Description : ce point d'extension est utilisé pour ajouter de nouvelles actions aux menus contextuels détenus par d'autres plug-in. La contribution d'action peut être réalisée pour un type d'objet spécifique (objectContribution) ou pour un menu contextuel spécifique. Lorsque objectContribution est utilisée, la contribution apparaît dans tous les menus contextuels des parties d'une vue ou d'un éditeur où sont sélectionnés des objets du type spécifié. En revanche, lorsque viewerContribution est utilisée, la contribution apparaît uniquement dans le menu contextuel des parties d'une vue ou d'un éditeur 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 ne sont pas appropriés, une contribution d'action peut utiliser le mécanisme filter. Dans ce cas, les attributs de l'objet cible sont décrits dans une série de paires nom-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.
L'activation et/ou la visibilité d'une action peuvent être définies respectivement à l'aide des éléments enablement et visibility. Ces deux élément contiennent une expression booléenne qui est évaluée pour déterminer l'activation et/ou la visibilité.
La syntaxe utilisée pour les éléments enablement et visibility est la même. Ils contiennent tous deux un seul sous-élément d'expression booléenne. Dans le cas le plus simple, il s'agira d'un élément objectClass, objectState, pluginState ou systemProperty. Dans le cas le plus complexe, les éléments and, or et not peuvent être combinés pour former une expression booléenne. Les éléments and et or doivent contenir chacun deux sous-éléments. L'élément not doit uniquement contenir un sous-élément.
Marques de configuration :
<!ELEMENT extension (objectContribution , viewerContribution)>
<!ATTLIST extension
point CDATA #REQUIRED
id CDATA #IMPLIED
name CDATA #IMPLIED
>
<!ELEMENT objectContribution (filter* , visibility? , menu* , action*)>
Cet élément est utilisé pour définir un groupe d'actions et/ou de menus pour tous les menus contextuels d'afficheurs pour lesquels les objets du type spécifié sont sélectionnés.
<!ATTLIST objectContribution<!ELEMENT viewerContribution (visibility? , menu* , action*)>
Cet élément est utilisé pour définir un groupe d'actions et/ou de menus pour le menu contextuel d'une partie d'une vue ou d'un éditeur spécifique.
<!ATTLIST viewerContribution<!ELEMENT action (selection* , enablement?)>
Cet élément définit une action que l'utilisateur peut appeler dans l'interface utilisateur.
<!ATTLIST actionpush | - comme une option de menu ou de barre d'outil ordinaire. | |
radio | - comme option de menu ou de barre d'outil de style bouton d'option. Les actions ayant le style bouton d'option à l'intérieur du même groupe de menu ou de barre d'outil se comportent comme un ensemble de boutons d'option. La valeur initiale est spécifiée par l'attribut state. | |
toggle | - comme une option de menu de style sélectionnée ou comme option de barre d'outil. La valeur initiale est spécifiée par l'attribut state. |
! | - aucun élément sélectionné | |
? | - aucun ou un élément sélectionné | |
+ | - un ou plusieurs éléments sélectionnés | |
multiple, 2+ | - deux ou plusieurs éléments sélectionnés | |
n | - nombre précis d'éléments sélectionnés Par exemple : enablesFor=" 4" active l'action uniquement lorsque 4 éléments sont sélectionnés | |
* | - n'importe quel nombre d'éléments sélectionnés |
Les critères d'activation pour une extension d'action sont initialement définis par enablesFor, selection et enablement. Toutefois, une fois le délégué d'action instancié, il peut contrôler l'état d'activation de l'action directement dans sa méthode selectionChanged.
<!ELEMENT filter EMPTY>
Cet élément permet d'évaluer l'état d'attribut de chaque objet de la sélection en cours. Une correspondance n'est obtenue que si chaque objet de la sélection possède l'état d'attribut spécifié. Chaque objet de la sélection doit implémenter l'interface org.eclipse.ui.IActionFilter ou s'y adapter.
<!ATTLIST filter<!ELEMENT menu (separator+ , groupMarker*)>
Cet élément est utilisé pour définir un nouveau menu.
<!ATTLIST menu<!ELEMENT separator EMPTY>
Cet élément permet de créer un séparateur de menus dans le nouveau menu.
<!ATTLIST separator<!ELEMENT groupMarker EMPTY>
Cet élément permet de créer un groupe désigné dans le nouveau menu. Contrairement à l'élément separator, il n'a pas de représentation visuelle dans le nouveau menu.
<!ATTLIST groupMarker<!ELEMENT selection EMPTY>
Cet élément permet d'aider à déterminer l'activation de l'action en fonction de la sélection en cours. Ignoré si l'élément enablement est spécifié.
<!ATTLIST selection<!ELEMENT enablement (and | or | not | objectClass | objectState | pluginState | systemProperty)>
Cet élément permet de définir l'activation de l'action.
<!ELEMENT visibility (and | or | not | objectClass | objectState | pluginState | systemProperty)>
Cet élément permet de définir la visibilité de l'action.
<!ELEMENT and (and | or | not | objectClass | objectState | pluginState | systemProperty)>
Cet élément représente une opération AND booléenne sur le résultat de l'évaluation de ses deux expressions de sous-éléments.
<!ELEMENT or (and | or | not | objectClass | objectState | pluginState | systemProperty)>
Cet élément représente une opération OR booléenne sur le résultat de l'évaluation de ses deux expressions de sous-éléments.
<!ELEMENT not (and | or | not | objectClass | objectState | pluginState | systemProperty)>
Cet élément représente une opération NOT booléenne sur le résultat de l'évaluation de ses expressions de sous-éléments.
<!ELEMENT objectClass EMPTY>
Cet élément permet d'évaluer la classe ou l'interface de chaque objet de la sélection en cours. Si chaque objet de la sélection implémente la classe ou l'interface spécifiée, l'expression est considérée comme vraie ("true").
<!ATTLIST objectClass<!ELEMENT objectState EMPTY>
Cet élément permet d'évaluer l'état d'attribut de chaque objet de la sélection en cours. Si chaque objet de la sélection possède l'état d'attribut spécifié, l'expression est considérée comme vraie ("true"). Pour évaluer ce type d'expression, chaque objet de la sélection doit implémenter l'interface org.eclipse.ui.IActionFilter ou s'y adapter.
<!ATTLIST objectState<!ELEMENT pluginState EMPTY>
Cet élément permet d'évaluer l'état d'un plug-in. L'état du plug-in peut être soit installed, soit activated.
<!ATTLIST pluginState<!ELEMENT systemProperty EMPTY>
Cet élément permet d'évaluer l'état d'une propriété système. La valeur de la propriété est extraite de java.lang.System.
<!ATTLIST systemProperty
<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" style="push" 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" style="toggle" state="true" menubarPath="additions" icon="icons/showXYZ.gif" helpContextId="com.xyz.show_action_context" class="com.xyz.actions.XYZShowActionDelegate"> </action> </viewerContribution> </extension>Dans cet exemple, l'action de contribution d'objet spécifiée ne sera activée que pour une seule sélection (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 le menu contextuel de la vue des tâches et ne sera pas affectée par la sélection effectuée dans la vue.
L'exemple ci-dessous illustre 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.C3" 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>L'exemple ci-dessous illustre une autre utilisation de l'élément de visibilité :
<extension point="org.eclipse.ui.popupMenus"> <viewerContribution id="com.xyz.C4" targetID="org.eclipse.ui.views.TaskList"> <visibility> <and> <pluginState id="com.xyz" value="activated"/> <systemProperty name="ADVANCED_MODE" value="true"/> </and> </visibility> <action id="com.xyz.showXYZ" label="&Show XYZ" style="push" menubarPath="additions" icon="icons/showXYZ.gif" helpContextId="com.xyz.show_action_context" class="com.xyz.actions.XYZShowActionDelegate"> </action> </viewerContribution> </extension>
Dans cet exemple, l'action spécifiée apparaîtra sous forme d'option de menu dans le menu contextuel de la vue des tâches, mais uniquement si le plug-in "com.xyz" est actif et si la propriété système spécifiée a pour valeur "true".
Informations d'API : la valeur de l'attribut d'action classe 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 menus contextuels appartenant à des é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 assurer la compatibilité avec les versions antérieures, org.eclipse.ui.IActionDelegate peut être implémenté pour les contributions d'objets.
Une extension de menu contextuel dans un composant n'est possible que 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 tous les menus contextuels 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 de 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.
Tout menu contextuel enregistré avec le plan de travail doit également contenir un point d'insertion standard ayant l'ID IWorkbenchActionConstants.MB_ADDITIONS. Les autres plug-in utiliseront cette valeur comme point de référence pour l'insertion. Le point d'insertion peut être défini par l'ajout d'un GroupMarker au menu à un emplacement approprié pour l'insertion.
Un objet du plan de travail qui correspond à 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 vérifier s'il implémente IActionFilter. Si l'opération échoue, le plan de travail demandera un filtre via le mécanisme IAdaptable.
Les libellés d'actions et de menus peuvent contenir des caractères spéciaux encodant des mnémoniques spécifiées à l'aide d'une perluète ('&') devant un caractère sélectionné dans le texte traduit. Comme le caractère perluète n'est pas autorisé dans les chaînes XML, utilisez l'entité de caractère &.
Si deux actions ou plus sont ajoutées à un menu par une extension, elles apparaîtront dans l'ordre inverse de celui dans le fichier plugin.xml. Il est admis que ce comportement n'est pas intuitif. Toutefois, il a été découvert après que l'API de la plateforme Eclipse a été figée. Si vous modifiez ce comportement maintenant, vous risquez d'endommager chaque plug-in qui utilise le comportement existant.
Les éléments selection et enablement s'excluent mutuellement. L'élément enablement peut remplacer l'élément selection en utilisant les sous-éléments objectClass et objectState. Par exemple, les lignes :
<selection class="org.eclipse.core.resources.IFile" name="*.java"> </selection>peut être exprimé à l'aide des lignes suivantes :
<enablement> <and> <objectClass name="org.eclipse.core.resources.IFile"/> <objectState name="extension" value="java"/> </and> </enablement>
Implémentation fournie : les vues du plan de travail possèdent des menus contextuels intégrés qui sont chargés avec un certain nombre d'actions. Les plug-in peuvent contribuer à ces menus. Si un afficheur dispose d'emplacements réservés pour ces contributions et qu'elles sont rendues publiques, les noms des emplacements sont utilisés comme chemins. Sinon, les actions et les sous-menus seront ajoutés à la fin du menu en incrustation.
Copyright (c) 2000, 2003 IBM Corporation and others.
All rights reserved. Ce programme et la documentation associée sont disponibles conformément aux dispositions de Common
Public License v1.0 qui accompagne cette distribution et qui est disponible à l'adresse
http://www.eclipse.org/legal/cpl-v10.html