Ce point d'extension permet au développeur du plug-in de définir des menus, des séparateurs, des groupes logiques et des options de menu dans l'application, des lignes d'état aux menus contextuels. Il permet également la définition d'ensembles de contributions (à savoir, des jeux d'actions), qui peuvent être activés ou désactivés par l'utilisateur final. En bref, le point d'extension menus contient tous les éléments de présentation (à l'exception des icônes) nécessaires pour la contribution à un menu ou à une zone de délimitation dans Eclipse.
Chaque élément contenu dans ce point d'extension est associé à un identificateur unique. C'est pourquoi ces éléments peuvent être référencés ailleurs sans avoir à répéter l'élément. Par exemple, l'identificateur peut être amené à organiser ou à définir un jeu d'actions. Cela permet également aux développeurs de plug-ins tiers de placer ces éléments à d'autres endroits dans l'interface, le cas échéant.
REMARQUE : Concernant la version 3.2, la seule partie de ce mécanisme d'extension ayant été implémentée est la partie associée aux contributions 'trim'. Tout ajout d'éléments, menus, barres d'état ou entrées de lignes d'état sera considéré comme des éléments NO-OP.
<!ELEMENT extension (item* , menu* , group* , widget*)>
<!ATTLIST extension
point CDATA #REQUIRED
id CDATA #IMPLIED
name CDATA #IMPLIED>
<!ELEMENT item (parameter* , location* , visibleWhen?)>
<!ATTLIST item
id CDATA #REQUIRED
commandId CDATA #REQUIRED
menuId CDATA #IMPLIED>
Un élément peut être une option de menu ou un élément de délimitation, selon l'endroit où il se trouve. Le texte et l'image associés à l'élément seront extraits de la commande.
org.eclipse.ui
peut être nommé org.eclipse.ui.item1
.<!ELEMENT menu (location* , visibleWhen?)>
<!ATTLIST menu
id CDATA #REQUIRED
label CDATA #IMPLIED>
Un menu peut apparaître associé à une option de menu ou figurer dans un menu de vue, un menu contextuel ou une barre de menus de niveau supérieur. Le développeur de plug-in peut supposer qu'un menu et une barre d'outils sont disponibles pour chaque vue et qu'il existe une barre de menus de niveau supérieur. Les menus contextuels doivent être enregistrés par programmation avant d'être utilisés (voir les Informations d'API).
Un menu ne peut contenir que des groupes.
org.eclipse.ui
peut être nommé org.eclipse.ui.menu1
.<!ATTLIST group
id CDATA #REQUIRED
separatorsVisible (true | false) "true">
Groupe logique. Il peut être visible (par exemple, les séparateurs sont tracés avant et après, le cas échéant) ou invisible. Par défaut, les groupes logiques sont visibles.
Un groupe peut contenir des menus, des options et d'autres groupes.
org.eclipse.ui
peut être nommé org.eclipse.ui.group1
.<!ELEMENT widget (location* , class? , visibleWhen? , layout?)>
<!ATTLIST widget
id CDATA #REQUIRED
class CDATA #REQUIRED>
Un élément de menu ou de délimitation associé à un accès direct aux widgets. Par exemple, ils peuvent servir à afficher une zone de liste déroulante. Seulement, cela implique que si un widget devient visible dans l'interface utilisateur, il provoquera le chargement de plug-ins. Utilisez cet élément avec précaution, dans la mesure où il peut être à l'origine de problèmes de performance. Il peut également provoquer des erreurs pour des fonctions comme la prise en charge de macros, la génération de script et d'autres éléments basés sur des commandes. Lorsqu'il est utilisé en tant qu'élément de délimitation, le widget n'entraînera le chargement du plug-in que lorsqu'il sera visible dans l'interface utilisateur.
org.eclipse.ui
peut être nommé org.eclipse.ui.widget1
.IWorkbenchWidget
. Les clients peuvent choisir d'utiliser l'implémentation par défaut AbstractWorkbenchTrimWidget
. Cette implémentation prend en charge la méthode 'init' et met le résultat en cache en vue de l'utiliser via sa méthode getWorkbenchWindow
.<!ELEMENT layout EMPTY>
<!ATTLIST layout
fillMajor (true | false)
fillMinor (true | false) >
Cet élément peut servir à indiquer différentes options de présentation pour les éléments ajoutés dans les emplacements trim
.
false
.false
.<!ELEMENT location (order? , (bar | part | popup))>
<!ATTLIST location
mnemonic CDATA #IMPLIED
imageStyle CDATA #IMPLIED>
Emplacement dans lequel un menu
, un groupe
, un élément
ou un widget
peut apparaître. Cet élément sert à contrôler les informations spécifiques à l'emplacement.
<!ELEMENT bar EMPTY>
<!ATTLIST bar
type (menu|trim)
path CDATA #IMPLIED>
Un élément seul dans un emplacement. Il peut s'agir de la barre de menus ou de la zone de délimitation. Si l'élément n'est pas qualifié, il s'agit du menu de niveau supérieur ou de la zone de délimitation. S'il est qualifié par un élément part
, il s'agit alors du menu ou de la zone de délimitation du composant.
menus
ou de la zone de délimitation
. Si l'ajout s'effectue au menu, l'élément sera associé à une structure de widget. En règle générale, cela signifie que l'utilisation d'éléments widget n'a pas beaucoup de sens, et qu'une icône pour une commande n'est pas forcément nécessaire. La valeur par défaut est menu
.
Si elle contribue à l'élément de délimitation
, la barre n'a généralement pas besoin de commande ou d'icône. Elle doit être alimenté par un widget qui affiche les informations de délimitation.
A l'intérieur de la zone de délimitation, le plan de travail définit cinq groupes généraux qui correspondent aux différents emplacements autour de la fenêtre :
vertical1
dans le plan de travail.'/'
comme caractère de séparation.<!ATTLIST class
class CDATA #REQUIRED>
Elément de classe prenant en charge la syntaxe d'analyse syntaxique de l'extension exécutable pour les éléments widget
et dynamic
.
IExecutableExtension
.<!ELEMENT visibleWhen (not | or | and | instanceof | test | systemTest | equals | count | with | resolve | adapt | iterate)>
<!ATTLIST visibleWhen
checkEnabled (true | false) "false">
Contrôle la visibilité de l'élément spécifié.
true
, aucun sous-élément ne doit exister. Cet attribut vérifie l'état activé de la commande, et rend l'élément correspondant visible si la commande est activée.<!ATTLIST part
id CDATA #IMPLIED
class CDATA #IMPLIED>
Elément dans un emplacement. Cet élément qualifie l'emplacement à mettre en référence avec un composant du plan de travail. Il peut s'agir d'une vue ou d'un éditeur. La qualification peut utiliser le nom de classe du composant (héritage compris), ou il peut désigner l'identificateur de la vue ou de l'éditeur.
Seuls id
et class
peuvent être spécifiés.
<!ELEMENT parameter EMPTY>
<!ATTLIST parameter
name CDATA #REQUIRED
value CDATA #REQUIRED>
Paramètre d'une extension exécutable ou d'une commande, selon l'endroit où il apparaît dans l'extension.
<!ELEMENT order EMPTY>
<!ATTLIST order
position (start|end|before|after)
relativeTo CDATA #IMPLIED>
Contrôle la position d'un menu, groupe, élément ou widget dans un endroit spécifique.
Cet attribut accepte les valeurs suivantes : start
(placer l'élément au début du conteneur) ; end
(placer l'élément à la fin du conteneur) ; after
(placer l'élément après l'élément apparenté dont l'ID correspond à ref
) ; et, before
(placer l'élément avant l'élément apparenté dont l'ID correspond à ref
). Un tri relatif peut être appliqué à n'importe quel élément du menu.
En cas de conflits, Eclipse optera pour un ordre arbitraire. La seule garantie offerte en cas de conflit est que l'ordre reste identique tant que ces conditions sont respectées :
position
a la valeur before
ou after
.<!ELEMENT popup EMPTY>
<!ATTLIST popup
id CDATA #IMPLIED
path CDATA #IMPLIED>
Partie d'un emplacement. Il indique que le menu, groupe, élément ou widget doit apparaître dans le menu en incrustation.
<!ELEMENT enablement (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>
Elément 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 à 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 en résultat de l'évaluation de son expression de 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 en résultat de l'évaluation de ses expressions de sous-élément.
<!ELEMENT or (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>
Cet élément représente une opération OR en résultat de l'évaluation de ses expressions de sous-élément.
<!ELEMENT instanceof EMPTY>
<!ATTLIST instanceof
value CDATA #REQUIRED>
Cet élément permet d'effectuer une instance de vérification de l'objet concerné. L'expression renvoie EvaluationResult.TRUE si le type de l'objet est un sous-type du type spécifié par la valeur de l'attribut. Dans le cas contraire, EvaluationResult.FALSE est renvoyé.
<!ELEMENT test EMPTY>
<!ATTLIST test
property CDATA #REQUIRED
args CDATA #IMPLIED
value CDATA #IMPLIED>
Cet élément permet d'évaluer l'état de la propriété de l'objet concerné. L'ensemble de propriétés testables peut être développé à l'aide du point d'extension du testeur de propriété. L'expression de test renvoie EvaluationResult.NOT_LOADED si le testeur de propriété effectuant le test réel 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 spécifiée via l'attribut value.
<!ELEMENT equals EMPTY>
<!ATTLIST equals
value CDATA #REQUIRED>
Cet élément permet d'effectuer une vérification d'égalité de l'objet concerné. L'expression renvoie EvaluationResult.TRUE si l'objet est égal à la valeur fournie par la valeur de l'attribut. Dans le cas contraire, EvaluationResult.FALSE est renvoyé.
<!ELEMENT count EMPTY>
<!ATTLIST count
value CDATA #REQUIRED>
Cet élément permet de tester le nombre d'éléments d'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 à inspecter pour tous les éléments enfant en objet référencé par la variable donnée. Si la variable ne peut pas être résolue, l'expression émet une exception ExpressionException lors de l'évaluation. Les enfants d'une expression with sont combinés à l'aide de 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 à inspecter pour tous les éléments enfant en objet référencé par la variable donnée. Si la variable ne peut pas être résolue, l'expression émet une exception ExpressionException lors de l'évaluation. Les enfants d'une expression with sont combinés à l'aide de 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 permet d'adapter l'objet actif en fonction du type spécifié par le type d'attribut. L'expression renvoie l'indication "non chargé" si l'adaptateur ou le type référencé n'est pas encore chargé. Elle émet une exception ExpressionException lors de la détermination de l'existence du nom du type. Les enfants d'une expression adapt sont combinés à l'aide de 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 permet d'effectuer une itération sur une variable qui est de type java.util.Collection. Si l'objet actif n'est pas du type java.util.Collection, une exception ExpressionException sera émise lors de l'évaluation de l'expression.
Une définition de menu typique est semblable à ce qui suit.
<menu id=
"com.mycompany.myplugin.projection"
label=
"%Folding.label"
>
<location mnemonic=
"%Folding.label.mnemonic"
>
<part id=
"AntEditor"
>
<popup id=
"#RulerContext"
path=
"rest"
/>
</part>
</location>
</menu>
Dans cet exemple, le développeur de plug-in ajoute à tous les composants qui sous-classent ou implémentent le type indiqué. Cela permet, par exemple d'ajouter des contributions à tous les éditeurs de texte.
<menu id=
"com.mycompany.myplugin.textEditorMenu"
label=
"Commandes texte"
>
<location mnemonic=
"X"
>
<part class=
"AbstractTextEditor"
>
<popup id=
"#RulerContext"
path=
"rest"
/>
</part>
</location>
</menu>
Il est possible d'associer l'aide à un menu.
<menu id=
"com.mycompany.myplugin.RunWithConfigurationAction"
label=
"Exécution avec la configuration"
helpContextId=
"run_with_configuration_context"
>
<location>
<bar />
</location>
</menu>
Dans un menu, il est possible de définir des groupes logiques. Ces groupes logiques peuvent être visibles (par exemple, les séparateurs sont tracés avant et après, le cas échéant) ou invisibles. Par défaut, les groupes logiques sont visibles.
<group id=
"com.mycompany.myplugin.stepGroup"
>
<location>
<bar path=
"org.eclipse.ui.run"
/>
</location>
</group>
<group id=
"com.mycompany.myplugin.stepIntoGroup"
separatorsVisible=
"false"
>
<location>
<bar path=
"org.eclipse.ui.run"
/>
</location>
</group>
Il est possible de placer les menus, le groupe, les éléments et les widgets dans plusieurs emplacements.
<item id=
"com.mycompany.myplugin.ToggleStepFilters"
commandId=
"com.mycompany.myplugin.ToggleStepFilters"
>
<location mnemonic=
"%mnemonic"
>
<bar path=
"org.eclipse.ui.run/emptyStepGroup"
/>
</location>
<location>
<part id=
"org.eclipse.debug.ui.DebugView"
>
<bar type=
"trim"
path=
"renderGroup"
/>
</part>
</location>
<location mnemonic=
"%mnemonic"
>
<part id=
"org.eclipse.debug.ui.DebugView"
>
<popup path=
"renderGroup"
/>
</part>
</location>
</item>
Si l'élément en incrustation est indiqué sans ID et sans élément composant parent, il s'applique à n'importe quel menu contextuel enregistré avec le plan de travail. Cela s'apparente au comportement des contributions d'objet. De même, un élément de niveau supérieur avec un ID affectera les menus contextuels enregistrés avec le nom indiqué.
<item id=
"com.mycompany.myplugin.ObjectContribution"
commandId=
"com.mycompany.myplugin.ObjectContribution"
>
<location>
<popup path=
"additions"
/>
</location>
</item>
Vous pouvez être amené à contrôler la visibilité d'un élément. Bien qu'il soit normalement préférable de maintenir une cohérence dans la présentation des menus et des barres d'outils, il est parfois nécessaire de masquer les éléments qui ne sont pas utiles dans l'immédiat. Cela est particulièrement vrai pour les menus contextuels, dans lesquels l'espace est limité. Dans ce cas, il vous faut définir un élément visibleWhen
. Cet élément est quasiment identique aux éléments activeWhen
et enabledWhen
définis dans le point d'extension gestionnaires.
<item id=
"com.mycompany.myplugin.ConvertToWatchExpression"
commandId=
"com.mycompany.myplugin.ConvertToWatchExpression"
>
<location mnemonic=
"%mnemonic"
>
<part id=
"org.eclipse.debug.ui.DebugView"
>
<popup path=
"additions"
/>
</part>
</location>
<visibleWhen>
<with variable=
"selection"
>
<iterate operator=
"and"
>
<not>
<instanceof value=
"IWatchExpression"
/>
</not>
<instanceof value=
"IExpression"
/>
</iterate>
</with>
</visibleWhen>
</item>
Le cas le plus courant consiste simplement à rendre un élément visible lorsque son gestionnaire est activé. Pour cela, on a recours au sucre syntaxique. Un attribut checkEnabled
est associé à l'élément visibleWhen
.
<item id=
"com.mycompany.myplugin.compareWithPatch"
commandId=
"com.mycompany.myplugin.compareWithPatch"
>
<location mnemonic=
"%mnemonic"
>
<part id=
"MyPart"
>
<popup path=
"additions"
/>
</part>
</location>
<visibleWhen checkEnabled=
"true"
/>
</item>
Un élément associé à une commande peut inclure des valeurs de paramètre. Si le paramètre d'un identificateur n'est pas défini, une erreur s'est produite. De même, si l'élément ne possède pas de commande, une erreur s'est produite.
<item id=
"com.mycompany.myplugin.RunHistory"
commandId=
"com.mycompany.myplugin.RunHistory"
>
<location>
<bar path=
"org.eclipse.ui.run"
/>
</location>
<parameter name=
"index"
value=
"1"
/>
</item>
Il est également possible d'indiquer un tri relatif. Cette opération s'effectue à l'aide de l'attribut d'ordre sur l'élément location. Cet attribut accepte les valeurs suivantes : start
(placer l'élément au début du conteneur) ; end (placer l'élément à la fin du conteneur) ; after
(placer l'élément après l'élément apparenté dont l'ID correspond à ref
) ; et, before
(placer l'élément avant l'élément apparenté dont l'ID correspond à ref
). Un tri relatif peut être appliqué à n'importe quel élément du menu.
<item id=
"com.mycompany.myplugin.MyFirstItem"
commandId=
"com.mycompany.myplugin.MyFirstCommand"
>
<location>
<order position=
"start"
/>
<bar path=
"org.eclipse.ui.run"
/>
</location>
</item>
<item id=
"com.mycompany.myplugin.MySecondItem"
commandId=
"com.mycompany.myplugin.MySecondCommand"
>
<location>
<order position=
"after"
relativeTo=
"com.mycompany.myplugin.MyFirstItem"
/>
<bar path=
"org.eclipse.ui.run"
/>
</location>
</item>
Si vous avez besoin d'un accès direct aux widgets (par exemple, pour afficher une zone de liste déroulante), vous pouvez utiliser un élément widget
. Seulement, cela implique que si un widget devient visible dans l'interface utilisateur, il provoquera le chargement de plug-ins.
<widget id=
"com.mycompany.myplugin.MyComboBoxSimple"
class=
"com.mycompany.myplugin.MyComboBox"
>
<location>
<bar type=
"trim"
path=
"myGroup"
/>
</location>
</widget>
<widget id=
"com.mycompany.myplugin.MyComboBoxParameterized1"
class=
"com.mycompany.myplugin.MyComboBox:a,b,c"
>
<location>
<bar type=
"trim"
path=
"myGroup"
/>
</location>
</widget>
<widget id=
"com.mycompany.myplugin.MyComboBoxParameterized2"
>
<class class=
"com.mycompany.myplugin.MyComboBox"
>
<parameter name=
"list"
value=
"a,b,c"
/>
<parameter name=
"selected"
value=
"c"
/>
<parameter name=
"editable"
value=
"false"
/>
</class>
<location>
<bar type=
"trim"
path=
"myGroup"
/>
</location>
</widget>
Vous pouvez également utiliser les widgets pour effectuer des ajouts dans la zone de délimitation du plan de travail. L'exemple ci-dessous illustre la définition d'un nouveau widget 'HeapStatus' devant se placer, par défaut, immédiatement après la zone de délimitation de la ligne d'état (à savoir, au bas de la fenêtre du plan de travail). Reportez-vous à la description de l'élément 'bar' pour plus d'informations sur les groupes prédéfinis.
Notez que les 'groupes' de délimitation peuvent être replacés dans d'autres zones de délimitations. L'élément relativeTo
des informations sur l'emplacement présumera que le groupe référencé réside dans son emplacement par défaut lors de la détermination du nouvel emplacement de délimitation. En général, on s'attend à ce que les éléments de contribution créent leur propre groupe en vue de recevoir le nouveau widget, ce qui permet à l'élément trim d'être replacé indépendamment des autres éléments trim. Il existe cependant une exception notable à ceci : le groupe 'status'.
<extension point=
"org.eclipse.ui.menus"
>
<group id=
"TestTrimAPI.heapStatusGroup"
separatorsVisible=
"true"
>
<location>
<bar type=
"trim"
/>
<order position=
"after"
relativeTo=
"status"
/>
</location>
</group>
<widget class=
"HeapStatusWidget"
id=
"TestTrimAPI.HeapStatus"
>
<location>
<bar path=
"heapStatusGroup"
type=
"trim"
/>
</location>
<layout fillMajor=
"false"
fillMinor=
"true"
/>
</widget>
</extension>
IWorkbenchPartSite.registerContextMenu
.
Copyright (c) 2005 IBM Corporation and others.
All rights reserved. Ce programme et les produits associés sont
distribués sous licence v1.0 et disponibles à
l'adresse suivante :
http://www.eclipse.org/legal/epl-v10.html