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. Les ajouts d'actions peuvent être effectués à un type d'objet spécifique (objectContribution) ou à un menu contextuel spécifique d'une partie de vue ou d'éditeur (viewerContribution). 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, l'ajout sera appliqué s'il est enregistré par rapport à un type commun de la sélection, si cela est possible. 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.

Les actions individuelles dans une contribution à un objet peuvent utiliser l'attribut enablesFor pour spécifier si elles devaient s'appliquer à un type de sélection unique, multiple ou à tout autre type.

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 d'un objet cible sont décrits dans une série de paires de nom/valeur. Les attributs qui s'appliquent à la sélection sont spécifiques au type et au-delà du domaine du workbench lui-même lequel délèguera le filtrage à ce niveau à la sélection en cours.

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ésultat 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 deux 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. Le statut du plugin peut être l'un des suivants : installed (equivalant au concept OSGi "resolved") ou activated (equivalant au concept OSGi "active").



<!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)*>

Un élément de racine générique. L'élément 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 en utilisant 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 son expression de sous-éléments.



<!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 ses expressions de 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 ses expressions de sous-éléments.



<!ELEMENT instanceof EMPTY>

<!ATTLIST instanceof

value CDATA #REQUIRED>

Cet élément est utilisé pour effectuer un contrôle instanceof sur l'objet en évidence. L'expression retourne EvaluationResult.TRUE si le type d'objet est un sous-type du type spécifié par la valeur de l'attribut. Autrement, c'est EvaluationResult.FALSE qui sera retourné.



<!ELEMENT test EMPTY>

<!ATTLIST test

property CDATA #REQUIRED

args     CDATA #IMPLIED

value    CDATA #IMPLIED>

Cet élément est utilisé pour évaluer le statut de la propriété de l'objet en évidence. Cet ensemble de propriétés testables peut être étendu en utilisant le point d'extension du testeur de propriétés. L'expression de test retourne EvaluationResult.NOT_LOADED si le testeur de propriété effectuant le test n'est pas encore chargé.



<!ELEMENT systemTest EMPTY>

<!ATTLIST systemTest

property CDATA #REQUIRED

value    CDATA #REQUIRED>

Teste une propriété du système en appelant la méthode System.getProperty et en comparant le résultat à la valeur spécifiée dans l'attribut de valeur.



<!ELEMENT equals EMPTY>

<!ATTLIST equals

value CDATA #REQUIRED>

Cet élément est utilisé pour effectuer un contrôle d'égalité d'un objet en évidence. Lexpression retourne EvaluationResult.TRUE si l'objet est égal à la valeur fournie par l'attribut valeur. Autrement, elle retournera EvaluationResult.FALSE.



<!ELEMENT count EMPTY>

<!ATTLIST count

value CDATA #REQUIRED>

Cet élément est utilisé 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 change l'objet à contrôler, pour tous ses éléments enfants, en l'objet référencé par la variable donnée. Si la variable ne peut être résolue, l'expression génèrera une exception ExpressionException lors de son évaluatiion. Les enfants d'une expression WITH sont combinés en utilisant 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 change l'objet à contrôler, pour tous ses éléments enfants, en l'objet référencé par la variable donnée. Si la variable ne peut être résolue, l'expression génèrera une exception ExpressionException lors de son évaluatiion. Les enfants d'une expression WITH sont combinés en utilisant 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 utilisé pour adapter l'objet en évidence au type spécifié par le type d'attribut. L'expression retourne non chargé si, soit l'adaptateur, soit le type référencé n'est pas encore chargé. Elle génère une exception ExpressionException durant l'évaluation si le nom du type n'existe pas du tout. Les enfants d'une expression adapt sont combinés en utilisant 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 utilisé pour itérer une variable de type java.util.Collection. Si l'objet en évidence n'est du type java.util.Collection, une exception ExpressionException sera généré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;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"

/>

</objectContribution>

<viewerContribution id=

"com.xyz.C2"

targetID=

"org.eclipse.ui.views.TaskList"

>

<action id=

"com.xyz.showXYZ"

label=

"&amp;Show XYZ"

style=

"toggle"

state=

"true"

menubarPath=

"additions"

icon=

"icons/showXYZ.gif"

helpContextId=

"com.xyz.show_action_context"

class=

"com.xyz.actions.XYZShowActionDelegate"

/>

</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;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".

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 workbench 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 workbench 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 workbench 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 workbench extrait le filtre pour la sélection en testant pour vérifier s'il implémente IActionFilter. Si l'opération échoue, le workbench 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 workbench 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.