Jeux d'actions

org.eclipse.ui.actionSets

Ce point d'extension sert à ajouter des menus, des options de menu et des boutons de barre d'outils dans les zones communes de la fenêtre Plan de travail. Ces contributions sont collectivement connues sous le nom de jeux d'actions et apparaissent dans la fenêtre Plan de travail lorsque l'utilisateur personnalise une perspective.

Une limite d'implémentation affecte actuellement les jeux d'actions. Il est important de définir l'intégralité de la structure du menu à référencer dans le jeu d'actions. Par exemple, si un autre jeu d'actions définit un menu appelé "exemple", il n'est pas possible d'utiliser le menu "exemple" existant. Il vous faut alors redéfinir le menu "exemple" dans chaque jeu d'actions qui souhaite l'utiliser.

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 (actionSet+)>

<!ATTLIST extension

point CDATA #REQUIRED

id    CDATA #IMPLIED

name  CDATA #IMPLIED>


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

<!ATTLIST actionSet

id          CDATA #REQUIRED

label       CDATA #REQUIRED

visible     (true | false)

description CDATA #IMPLIED>

Cet élément est employé pour définir un groupe d'actions et/ou de 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|pulldown) "push"

state            (true | false)

pulldown         (true | false)

class            CDATA #IMPLIED

retarget         (true | false)

allowLabelUpdate (true | false)

enablesFor       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. 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 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 l'un des suivants : installé (équivalent au concept "resolved" d'OSGi) ou activé (équivalent au concept "active" d'OSGi).



<!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.



L'exemple ci-dessous illustre un ensemble d'actions (notez les sous-éléments et le mode d'utilisation des attributs) :

    

<extension point =

"org.eclipse.ui.actionSets"

>

<actionSet id=

"com.xyz.actionSet"

label=

"Mes actions"

>

<menu id=

"com.xyz.xyzMenu"

label=

"XYZ Menu"

path=

"additions"

>

<separator name=

"group1"

/>

<separator name=

"option1"

/>

</menu>

<action id=

"com.xyz.runXYZ"

label=

"&amp;Run XYZ Tool"

style=

"toggle"

state=

"false"

menubarPath=

"com.xyz.xyzMenu/group1"

icon=

"icons/runXYZ.gif"

tooltip=

"Exécuter l'outil XYZ"

helpContextId=

"com.xyz.run_action_context"

class=

"com.xyz.actions.RunXYZ"

enablesFor=

"1"

>

<selection class=

"org.eclipse.core.resources.IFile"

name=

"*.java"

/>

</action>

<action id=

"com.xyz.runABC"

label=

"&amp;Run ABC Tool"

style=

"push"

menubarPath=

"com.xyz.xyzMenu/group1"

toolbarPath=

"Normal/XYZ"

icon=

"icons/runABC.gif"

tooltip=

"Run ABC Tool"

helpContextId=

"com.xyz.run_abc_action_context"

retarget=

"true"

allowLabelUpdate=

"true"

>

<enablement>

<and>

<objectClass name=

"org.eclipse.core.resources.IFile"

/>

<not>

<objectState name=

"extension"

value=

"java"

/>

</not>

</and>

</enablement>

</action>

<action id=

"com.xyz.runDEF"

label=

"&amp;Run DEF Tool"

style=

"radio"

state=

"true"

menubarPath=

"com.xyz.xyzMenu/option1"

icon=

"icons/runDEF.gif"

tooltip=

"Run DEF Tool"

class=

"com.xyz.actions.RunDEF"

helpContextId=

"com.xyz.run_def_action_context"

>

</action>

<action id=

"com.xyz.runGHI"

label=

"&amp;Run GHI Tool"

style=

"radio"

state=

"false"

menubarPath=

"com.xyz.xyzMenu/option1"

icon=

"icons/runGHI.gif"

tooltip=

"Run GHI Tool"

class=

"com.xyz.actions.RunGHI"

helpContextId=

"com.xyz.run_ghi_action_context"

>

</action>

<action id=

"com.xyz.runJKL"

label=

"&amp;Run JKL Tool"

style=

"radio"

state=

"false"

menubarPath=

"com.xyz.xyzMenu/option1"

icon=

"icons/runJKL.gif"

tooltip=

"Run JKL Tool"

class=

"com.xyz.actions.RunJKL"

helpContextId=

"com.xyz.run_jkl_action_context"

>

</action>

</actionSet>

</extension>

Dans l'exemple ci-dessus, le jeu d'actions spécifié, désigné par "Mes actions", n'est pas initialement visible dans chaque perspective car l'attribut visible n'est pas spécifié.

L'action XYZ apparaîtra sous forme de case à cocher de menu, initialement non cochée. Elle n'est activée que si le nombre de sélections est égal à 1 et si la sélection contient une ressource de fichier Java.

L'action ABC apparaît à la fois dans le menu et dans la barre d'outils. Elle n'est activée que si la sélection ne contient pas de ressource de fichier Java. Comme il s'agit d'une action de redirection de libellé, aucun attribut class n'est proposé.

Les actions DEF, GHI et JKL apparaissent en tant que boutons d'option de menu. Elles sont en permanence activées, quel que soit l'état de la sélection courante.

La valeur de l'attribut class doit correspondre au nom qualifié complet d'une classe implémentant org.eclipse.ui.IWorkbenchWindowActionDelegate ou org.eclipse.ui.IWorkbenchWindowPulldownDelegate. Le second devant être implémenté lorsque l'attribut style a la valeur pulldown. Cette classe est le gestionnaire chargé d'exécuter l'action. Si l'attribut retarget a la valeur true, il est ignoré et ne doit pas être fourni. 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.

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

Notez que le plan de travail ne génère pas de menus à la demande de plug-ins. Les chemins de menus doit faire référence à des menus existant déjà.

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 qui est utilisé 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>

Les plug-ins peuvent utiliser ce point d'extension pour ajouter des menus de niveau supérieur. Les plug-ins peuvent également définir des groupes désignés qui permettent aux autres plug-ins d'y ajouter leurs 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 groupes par défaut dans une fenêtre du plan de travail sont définis dans l'interface IWorkbenchActionConstants. Ces constantes peuvent être utilisées dans du code pour une contribution dynamique. Les valeurs peuvent être également copiées dans un fichier XML pour une intégration étroite aux menus et à la barre d'outils existants dans le plan de travail.

Plusieurs éléments des menus et de la barre d'outils de la fenêtre du plan de travail sont définis par algorithme. Dans ce cas, un mécanisme distinct doit être utilisé pour étendre la fenêtre. Par exemple, ajoutez une nouvelle vue de plan de travail pour faire apparaître une nouvelle option dans le menu Perspective. Les extensions Importation, Exportation et Nouveaux assistants sont également ajoutées automatiquement à la fenêtre.