Menus en incrustation

org.eclipse.ui.popupMenus

Ce point d'extension sert à ajouter de nouvelles actions aux menus contextuels 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 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éments 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.

<!ELEMENT extension (objectContribution , viewerContribution)>

<!ATTLIST extension

point CDATA #REQUIRED

id    CDATA #IMPLIED

name  CDATA #IMPLIED>


<!ELEMENT objectContribution (filter* , visibility? , enablement? , menu* , action*)>

<!ATTLIST objectContribution

id          CDATA #REQUIRED

objectClass CDATA #REQUIRED

nameFilter  CDATA #IMPLIED

adaptable   (true | false) "false">

Cet élément est employé pour définir un groupe d'actions et/ou de menus pour tous les menus contextuels d'afficheur où des objets d'un type précis sont sélectionnés.



<!ELEMENT viewerContribution (visibility? , menu* , action*)>

<!ATTLIST viewerContribution

id       CDATA #REQUIRED

targetID CDATA #REQUIRED>

Cet élément est employé pour définir un groupe d'actions et/ou de menus pour un menu contextuel de vue ou d'éditeur spécifique.



<!ELEMENT action (selection* , enablement?)>

<!ATTLIST action

id               CDATA #REQUIRED

label            CDATA #REQUIRED

definitionId     CDATA #IMPLIED

menubarPath      CDATA #IMPLIED

icon             CDATA #IMPLIED

helpContextId    CDATA #IMPLIED

style            (push|radio|toggle|pulldown)

state            (true | false)

class            CDATA #REQUIRED

enablesFor       CDATA #IMPLIED

overrideActionId CDATA #IMPLIED

tooltip          CDATA #IMPLIED>

Cet élément définit une action que l'utilisateur peut appeler dans l'interface utilisateur.



<!ELEMENT filter EMPTY>

<!ATTLIST filter

name  CDATA #REQUIRED

value CDATA #REQUIRED>

Cet élément est employé pour évaluer l'état d'attribut de chaque objet dans 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.



<!ELEMENT menu (separator+ , groupMarker*)>

<!ATTLIST menu

id    CDATA #REQUIRED

label CDATA #REQUIRED

path  CDATA #IMPLIED>

Cet élément est employé pour définir un nouveau menu.



<!ELEMENT separator EMPTY>

<!ATTLIST separator

name  CDATA #REQUIRED>

Cet élément est employé pour créer un séparateur de menu dans le nouveau menu.



<!ELEMENT groupMarker EMPTY>

<!ATTLIST groupMarker

name  CDATA #REQUIRED>

Cet élément est employé pour créer un groupe nommé dans le nouveau menu. Contrairement à l'élément separator, il n'a pas de représentation visuelle dans le nouveau menu.



<!ELEMENT selection EMPTY>

<!ATTLIST selection

class CDATA #REQUIRED

name  CDATA #IMPLIED>

Cet élément est employé pour permettre de déterminer l'activation de l'action en fonction de la sélection en cours. Ignoré si l'élément enablement est spécifié.



<!ELEMENT enablement (and | or | not | objectClass | objectState | pluginState | systemProperty)>

Cet élément est employé pour définir l'activation pour l'extension.



<!ELEMENT visibility (and | or | not | objectClass | objectState | pluginState | systemProperty)>

Cet élément est employé pour définir la visibilité pour l'extension.



<!ELEMENT and (and | or | not | objectClass | objectState | pluginState | systemProperty)>

Cet élément représente une opération booléenne AND sur le résultat d'é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 booléenne OR sur le résulta d'é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 booléenne NOT sur le résultat d'évaluation de ses expressions de sous-éléments.



<!ELEMENT objectClass EMPTY>

<!ATTLIST objectClass

name  CDATA #REQUIRED>

Cet élément est employé pour évaluer la classe ou l'interface de chaque objet dans 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").



<!ELEMENT objectState EMPTY>

<!ATTLIST objectState

name  CDATA #REQUIRED

value CDATA #REQUIRED>

Cet élément est employé pour évaluer l'état d'attribut de chaque objet dans 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.



<!ELEMENT pluginState EMPTY>

<!ATTLIST pluginState

id    CDATA #REQUIRED

value (installed|activated) "installed">

Cet élément est employé pour évaluer l'état d'un plug-in. L'état du plug-in peut être soit installed, soit activated.



<!ELEMENT systemProperty EMPTY>

<!ATTLIST systemProperty

name  CDATA #REQUIRED

value CDATA #REQUIRED>

Cet élément est employé pour évaluer l'état d'une propriété système. La valeur de la propriété est extraite de java.lang.System.



<!ELEMENT enablement (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>

Elément racine générique. Il peut être utilisé dans un point d'extension pour définir son expression d'activation. Les enfants d'une expression d'activation sont combinés à l'aide de l'opérateur and.



<!ELEMENT not (not | and | or | instanceof | test | systemTest | equals | count | with | resolve | adapt | iterate)>

Cet élément représente une opération NOT sur le résultat d'évaluation de l'expression de son sous-élément.



<!ELEMENT and (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>

Cet élément représente une opération AND sur le résultat d'évaluation de toutes les expressions de ses sous-éléments.



<!ELEMENT or (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>

Cet élément représente une opération OR sur le résultat d'évaluation de toutes les expressions de son sous-élément.



<!ELEMENT instanceof EMPTY>

<!ATTLIST instanceof

value CDATA #REQUIRED>

Cet élément est employé pour effectuer une vérification d'instance de l'objet activé. L'expression renvoie EvaluationResult.TRUE si le type d'objet est un sous-type du type spécifié par la valeur de l'attribut. Sinon, elle retourne EvaluationResult.FALSE.



<!ELEMENT test EMPTY>

<!ATTLIST test

property CDATA #REQUIRED

args     CDATA #IMPLIED

value    CDATA #IMPLIED>

Cet élément est employé pour évaluer l'état de propriété de l'objet activé. L'ensemble des propriétés pouvant être testées peut être étendu à l'aide du point d'extension de testeur de propriétés. L'expression de test renvoie EvaluationResult.NOT_LOADED si le testeur de propriétés n'est pas encore chargé.



<!ELEMENT systemTest EMPTY>

<!ATTLIST systemTest

property CDATA #REQUIRED

value    CDATA #REQUIRED>

Teste une propriété système en appelant la méthode System.getProperty et compare le résultat avec la valeur indiquée par l'attribut.



<!ELEMENT equals EMPTY>

<!ATTLIST equals

value CDATA #REQUIRED>

Cet élément est employé pour effectuer une vérification d'équivalence de l'objet activé. L'expression renvoie EvaluationResult.TRUE si l'objet équivaut à la valeur indiquée par l'attribut. Sinon, elle retourne EvaluationResult.FALSE.



<!ELEMENT count EMPTY>

<!ATTLIST count

value CDATA #REQUIRED>

Cet élément est employé pour tester le nombre d'éléments dans une collection.



<!ELEMENT with (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>

<!ATTLIST with

variable CDATA #REQUIRED>

Cet élément remplace l'objet à contrôler pour tous ses éléments enfants par celui auquel la variable donnée fait référence. Si la variable ne peut être résolue, l'expression renvoie ExpressionException à son évaluation. Les enfants avec une expression sont combinés avec l'opérateur and.



<!ELEMENT resolve (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>

<!ATTLIST resolve

variable CDATA #REQUIRED

args     CDATA #IMPLIED>

Cet élément remplace l'objet à contrôler pour tous ses éléments enfants par celui auquel la variable donnée fait référence. Si la variable ne peut être résolue, l'expression renvoie ExpressionException à son évaluation. Les enfants avec une expression sont combinés avec l'opérateur and.



<!ELEMENT adapt (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>

<!ATTLIST adapt

type CDATA #REQUIRED>

Cet élément est employé pour adapter l'objet activé au type indiqué par le type d'attribut. L'expression renvoie not loaded si l'adaptateur ou le type référencés ne sont pas encore chargés. Elle lance ExpressionException au cours de l'évaluation si le nom du type n'existe pas. Les enfants d'une expression d'adaptation sont combinés avec l'opérateur and.



<!ELEMENT iterate (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>

<!ATTLIST iterate

operator (or|and) >

Cet élément est employé pour itérer sur une variable de type java.util.Collection. Si l'objet activé n'est pas de type java.util.Collection, une exception ExpressionException est lancée lors de l'évaluation de l'expression.



L'exemple ci-dessous illustre le point d'extension d'un menu local :

   

<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=

"&Outils Java XYZ"

>

<separator name=

"group1"

/>

</menu>

<action id=

"com.xyz.runXYZ"

label=

"&amp;Exécuter l'outil XYZ"

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=

"&amp;Afficher 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=

"Outil action terminée de priorité élevée"

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=

"&amp;Afficher 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".

La valeur de l'attribut class doit correspondre au nom qualifié complet d'une classe Java implémentant org.eclipse.ui.IObjectActionDelegate dans le cas de contributions d'objets, org.eclipse.ui.IViewActionDelegate pour les contributions à des menus contextuels appartenant à des vues ou org.eclipse.ui.IEditorActionDelegate pour les contributions à des 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-ins 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 &amp;.

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>

Le plan de travail fournit des menus contextuels intégrés chargés avec un nombre d'actions. Les plug-ins 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.