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.
push | - 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. | |
pulldown | - comme option de menu en cascade. |
! | - 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>
<!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.
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.<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=
"&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=
"&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>
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.
L'exemple ci-dessous illustre une autre utilisation de l'élément de visibilité :<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>
<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=
"&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".
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 &.
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 :
peut être exprimé à l'aide des lignes suivantes :<selection class=
"org.eclipse.core.resources.IFile"
name=
"*.java"
>
</selection>
<enablement>
<and>
<objectClass name=
"org.eclipse.core.resources.IFile"
/>
<objectState name=
"extension"
value=
"java"
/>
</and>
</enablement>
Copyright (c) 2000, 2004 IBM Corporation and others.
All rights reserved. Ce programme et les produits qui l'accompagnent sont
fournis sous licence v1.0 associée à cette distribution et disponibles à
l'adresse suivante :
http://www.eclipse.org/legal/cpl-v10.html