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.
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 jeu 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é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.
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=
"&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=
"&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>
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=
"&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".
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 &.
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, 2005 IBM Corporation and others.
All rights reserved. Ce programme et les produits associés sont distribués sous licence Eclipse v1.0 et disponibles à l'adresse suivante :http://www.eclipse.org/legal/epl-v10.html