Menus Editeur, Barres d'outils et Actions

org.eclipse.ui.editorActions

Ce point d'extension sert à ajouter des actions au menu et à la barre d'outils des éditeurs enregistrés par d'autres plug-ins.

Le jeu de contributions initial d'un éditeur est défini par un autre point d'extension (org.eclipse.ui.editors). Un jeu d'actions est créé et partagé par toutes les instances du même type d'éditeur. Une fois appelée, cette action agit sur l'éditeur actif. Ce point d'extension suit le même schéma. Chaque extension d'action est créée et partagée par toutes les instances du même type d'éditeur. La classe d'action est requise pour implémenter org.eclipse.ui.IEditorActionDelegate. L'éditeur actif est transmis au délégué en invoquant IEditorActionDelegate.setActiveEditor.

L'activation et/ou visibilité d'une action se définissent respectivement à l'aide des éléments enablement et visibility. Ces deux éléments contiennent une expression booléenne qui entraîne l'activation et/ou la visibilité.

La syntaxe des éléments enablement et visibility est identique. Ils contiennent chacun un unique sous-élément d'expression booléenne. Dans les cas les plus simples, il s'agit d'un élément objectClass, objectState, pluginState ou systemProperty. Dans les cas plus complexes, les éléments and, or et not peuvent être combinés pour former une expression booléenne. Les éléments and et or doivent chacun contenir 2 sous-éléments. L'élément not ne doit en contenir qu'un.

<!ELEMENT extension (editorContribution+)>

<!ATTLIST extension

point CDATA #REQUIRED

id    CDATA #IMPLIED

name  CDATA #IMPLIED>


<!ELEMENT editorContribution (menu* , action*)>

<!ATTLIST editorContribution

id       CDATA #REQUIRED

targetID CDATA #REQUIRED>

Cet élément est employé pour définir un groupe d'actions d'éditeur et/ou menus.



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

<!ATTLIST action

id            CDATA #REQUIRED

label         CDATA #REQUIRED

accelerator   CDATA #IMPLIED

definitionId  CDATA #IMPLIED

menubarPath   CDATA #IMPLIED

toolbarPath   CDATA #IMPLIED

icon          CDATA #IMPLIED

disabledIcon  CDATA #IMPLIED

hoverIcon     CDATA #IMPLIED

tooltip       CDATA #IMPLIED

helpContextId CDATA #IMPLIED

style         (push|radio|toggle) "push"

state         (true | false)

class         CDATA #REQUIRED

enablesFor    CDATA #IMPLIED

actionID      CDATA #IMPLIED>

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



<!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. Il ne possède aucune représentation visuelle dans le nouveau menu, à la différence de l'élément separator.



<!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 n'est pas 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 de l'évaluation des expressions de ses deux 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 de l'évaluation des expressions de ses deux 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 de l'évaluation des expressions de ses 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 vraie.



<!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 présente l'état d'attribut spécifié, l'expression est considérée vraie. Pour évaluer ce type d'expression, chaque objet de la sélection doit implémenter (ou s'adapter à) l'interface org.eclipse.ui.IActionFilter.



<!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 (équivalent au concept OSGi "resolved"), soit activated (équivalent 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é système est déterminée en appelant java.lang.System.



L'exemple ci-dessous illustre l'extension d'une action d'éditeur :

   

<extension point=

"org.eclipse.ui.editorActions"

>

<editorContribution id=

"com.xyz.xyzContribution"

targetID=

"com.ibm.XMLEditor"

>

<menu id=

"XYZ"

label=

"&Menu XYZ"

>

<separator name=

"group1"

/>

</menu>

<action id=

"com.xyz.runXYZ"

label=

"&amp;Run XYZ Tool"

menubarPath=

"XYZ/group1"

toolbarPath=

"Normal/additions"

style=

"toggle"

state=

"true"

icon=

"icons/runXYZ.gif"

tooltip=

"Exécuter l'outil XYZ"

helpContextId=

"com.xyz.run_action_context"

class=

"com.xyz.actions.RunXYZ"

>

<selection class=

"org.eclipse.core.resources.IFile"

name=

"*.java"

/>

</action>

</editorContribution>

</extension>

Dans cet exemple, l'action spécifiée apparaîtra sous forme de case à cocher dans le nouveau menu de niveau supérieur nommé "XYZ Menu" et sous forme de bouton dans la barre d'outils. L'action est activée si la sélection ne contient que des ressources de fichier Java.

Voici un autre exemple de point d'extension d'action d'éditeur :

   

<extension point=

"org.eclipse.ui.editorActions"

>

<editorContribution id=

"com.xyz.xyz2Contribution"

targetID=

"com.ibm.XMLEditor"

>

<menu id=

"XYZ2"

label=

"&Menu XYZ2"

path=

"edit/additions"

>

<separator name=

"group1"

/>

</menu>

<action id=

"com.xyz.runXYZ2"

label=

"&Exécuter l'outil XYZ2"

menubarPath=

"edit/XYZ2/group1"

style=

"push"

icon=

"icons/runXYZ2.gif"

tooltip=

"Exécuter l'outil XYZ2"

helpContextId=

"com.xyz.run_action_context2"

class=

"com.xyz.actions.RunXYZ2"

>

<enablement>

<and>

<objectClass name=

"org.eclipse.core.resources.IFile"

/>

<not>

<objectState name=

"extension"

value=

"java"

/>

</not>

</and>

</enablement>

</action>

</editorContribution>

</extension>

Dans cet exemple, l'action spécifiée apparaîtra sous forme d'option dans le sous-menu nommé "XYZ2 Menu" du menu "Edit" de niveau supérieur. L'action est activée si la sélection ne contient aucune ressource de fichier Java.

La valeur de l'attribut class doit correspondre au nom qualifié complet d'une classe Java implémentant org.eclipse.ui.IEditorActionDelegate. Cette classe est chargée aussi tardivement que possible afin d'éviter le chargement du plug-in tout entier avant que cela ne soit réellement nécessaire. La méthode setActiveEditor sera appelée chaque fois qu'un éditeur du type spécifié est activé. Un seul jeu d'actions et de menus sera créé pour toutes les instances du type d'éditeur spécifié, quel que soit le nombre d'instances d'éditeur ouverts dans le plan de travail.

Ce point d'extension peut être utilisé pour ajouter des actions aux menus précédemment créés par l'éditeur cible. De plus, des menus et des actions peuvent être ajoutés à la fenêtre du plan de travail. Les identificateurs d'actions et les principaux groupes de la fenêtre du plan de travail sont définis dans org.eclipse.ui.IWorkbenchActionConstants. Ils doivent être utilisés comme point de référence pour l'ajout de nouvelles actions. Des menus de niveau supérieur sont créés à l'aide de la valeur suivante pour l'attribut path :

L'omission de l'attribut path entraîne l'ajout du nouveau menu au groupe de la barre de menus additions.

Les actions et les menus ajoutés à ces chemins d'accès ne s'affichent que lorsque l'éditeur associé est actif. Lorsque l'éditeur est fermé, les menus et les actions sont supprimés.

Les critères d'activation d'une extension d'action d'action sont initialement définis par enablesFor, et aussi par selection ou enablement. Cependant, 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.

Les libellés d'actions et de menus peuvent contenir des caractères spéciaux qui encodent les mnémoniques en respectant les règles suivantes :

  1. Les mnémoniques sont spécifiées à l'aide du caractère perluète (&) placé 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 ou une barre d'outils par une extension, elles apparaîtront dans l'ordre inverse de celui dans le fichier plugin.xml. Ce comportement est intuitif. Toutefois, il a été découvert qu'une fois l'API de plateforme Eclipse figée. Si vous modifiez ce comportement maintenant, vous endommagez chaque plug-in utilisant le comportement existant.

Les éléments selection et enablement sont mutuellement exclusifs. L'élément enablement peut remplacer l'élément selection en utilisant les sous-éléments objectClass et objectState. Par exemple :

 

<selection class=

"org.eclipse.core.resources.IFile"

name=

"*.java"

>

</selection>

peut s'exprimer comme suit :
 

<enablement>

<and>

<objectClass name=

"org.eclipse.core.resources.IFile"

/>

<objectState name=

"extension"

value=

"java"

/>

</and>

</enablement>

Le plan de travail fournit un éditeur de texte intégré par défaut. Les plug-ins peuvent contribuer à cet éditeur par défaut ou à ceux fournis par d'autres plug-ins.