Expressions

Description : Les expressions booléennes permettent de définir la visibilité et l'activation de nombreuses extensions d'action figurant dans le plan de travail. Par exemple, un élément enablement peut être défini dans une action d'extension.  Cet élément contient une expression booléenne qui définit les critères d'activation de l'action. Un élément visibility peut être défini pour une extension d'action de menu en incrustation. Cet élément contient une expression booléenne qui définit les critères de visibilité de l'action.

Le format de la syntaxe de l'expression est identique pour tous les emplacements auxquels se trouve l'expression booléenne. L'élément racine enablement et visibility doit contenir le sous-élément.  Dans le cas le plus simple, il consiste en un élément objectClass, objectState, systemProperty, ou pluginState. Dans le cas le plus complexe, les éléments and, or et not peuvent être combinés en une expression booléenne. Un élément and ou or peut contenir un ou plusieurs sous-éléments. Un élément not ne doit contenir qu'un seul sous-élément.

Un élément objectClass permet d'évaluer la classe de chaque objet de la sélection. L'attribut de nom de l'élément objectClass contient un nom de classe complet. Si chaque objet de la sélection implémente cette classe, la valeur true est considérée comme attribuée à cette expression.

Un élément objectState permet d'évaluer l'état de chaque objet de la sélection. Dans la plupart des situations, l'activation ou la visibilité d'une action peut être déterminée par type de sélection. Dans d'autres situations, cela ne suffit pas, et l'activation et la visibilité doivent être déterminées d'après l'état de la sélection. Par exemple, vous pouvez utiliser une action pour tous les objets de type IFile qui sont en lecture seule. Ces critères de lecture seule ne peuvent être déclarés qu'en définissant un élément objectState. Cette définition peut être effectuée en suivant le format ci-après.

<objectState name="readOnly" value="true"/>
Dans le plan de travail, il est très difficile d'évaluer cette expression, car les attributs d'un objet sont propres au type de l'objet et dépassent le domaine du plan de travail lui-même. Le plan de travail collabore donc avec les objets de la sélection pour évaluer l'expression. A cet effet, il utilise un élément IActionFilter, c'est-à-dire une stratégie d'évaluation pour les éléments objectState. Lorsqu'un élément objectState est évalué, le plan de travail recherche un élément IActionFilter dans chaque objet de la sélection en vérifiant si l'objet implémente l'élément IActionFilter. Si tel n'est pas le cas, le plan de travail recherche un filtre en utilisant le mécanisme IAdaptable. S'il trouve un filtre, il lui transmet les attributs objectState pour vérifier s'ils correspondent à l'état de l'objet sélectionné. Si tel est le cas, le terme est considéré comme vrai ("true"). S'il n'existe aucun filtre d'action ou aucune occurrence, le terme est considéré comme faux ("false").

Les vues et les éditeurs sont encouragés à définir un élément IActionFilter pour chaque objet de leur sélection.  Cela facilite l'ajout d'actions complètes à ces vues ou à ces éditeurs par d'autres développeurs de plug-in.

Les éléments systemProperty permettent d'évaluer l'état de certaines propriétés système. La valeur de la propriété système est déterminée en appelant System.getProperty.

Les éléments pluginState permettent d'évaluer l'état d'un plug-in. Un plug-in peut avoir l'état "installé" ou "activé".

Depuis la version 2.0

Marques de configuration :

   <!ELEMENT visibility (and | or | not | objectClass | objectState | systemProperty
        | pluginState)>

   <!ELEMENT enablement (and | or | not | objectClass | objectState | systemProperty
        | pluginState)>

   <!ELEMENT and (and | or | not | objectClass | objectState | systemProperty | pluginState)*>

   <!ELEMENT or (and | or | not | objectClass | objectState | systemProperty | pluginState)*>

   <!ELEMENT not (and | or | not | objectClass | objectState | systemProperty | pluginState)>

   <!ELEMENT objectClass EMPTY>
   <!ATTLIST objectClass
      name       CDATA #REQUIRED
   >

   <!ELEMENT objectState EMPTY>
   <!ATTLIST objectState
      name       CDATA #REQUIRED
      value      CDATA #REQUIRED
   >    <!ELEMENT systemProperty EMPTY>
   <!ATTLIST systemProperty
      name       CDATA #REQUIRED
      value      CDATA #REQUIRED
   >    <!ELEMENT pluginState EMPTY>
   <!ATTLIST pluginState
      id         CDATA #REQUIRED
      value      (installed | activated)
   >
  • id : Correspond à l'ID d'un plug-in qui est ou n'est peut-être pas enregistré dans le registre du plug-in.
  • value : Correspond à l'état requis pour le plug-in. Actuellement, les deux états acceptés sont "installé" et "activé".
  • Exemples :

    L'exemple suivant illustre un ensemble d'actions qui utilise l'élément enablement. Cet ensemble d'actions déclare un menu dont le libellé est List Element puis lui intègre des actions activées par une sélection d'objets ListElements présentant divers états. Les objets ListElement ont deux attributs : name (une chaîne) et flag (une valeur booléenne). Dans cet exemple, l'action All (A tag) est activée lorsqu'un objet ListElement est sélectionné. L'action Red (B tag) est activée lorsqu'un objet ListElement avec name = red est sélectionné. L'action Not Red (C tag) est quant à elle activée lorsqu'un objet ListElement avec name != red est sélectionné.

    <extension point = "org.eclipse.ui.actionSets">
        <actionSet id="org.eclipse.ui.tests.internal.ListElementActions"
            label="List Element">
            <menu id="org.eclipse.ui.tests.internal.ListElementMenu"
                label="List Element"
                path="additions">
                <separator name="group1"/>
            </menu>
    A tag     <action id="org.eclipse.ui.tests.internal.ac1"
                label="All"
                menubarPath="org.eclipse.ui.tests.internal.ListElementMenu/group1"
                class="org.eclipse.ui.tests.api.MockActionDelegate"
                enablesFor="1">
                <enablement>
                     <objectClass name="org.eclipse.ui.tests.api.ListElement"/>
                </enablement>
            </action>
    B tag     <action id="org.eclipse.ui.tests.internal.ac2"
                label="Red"
                menubarPath="org.eclipse.ui.tests.internal.ListElementMenu/group1"
                class="org.eclipse.ui.tests.api.MockActionDelegate"
                enablesFor="1">
                <enablement>
                 <and>
                  <objectClass name="org.eclipse.ui.tests.api.ListElement"/>
                  <objectState name="name" value="red"/>
                 </and>
                </enablement>
            </action>
    C tag     <action id="org.eclipse.ui.tests.internal.ac3"
                label="Not Red"
                menubarPath="org.eclipse.ui.tests.internal.ListElementMenu/group1"
                class="org.eclipse.ui.tests.api.MockActionDelegate"
                enablesFor="1">
                <enablement>
                 <and>
                  <objectClass name="org.eclipse.ui.tests.api.ListElement"/>
                   <not>
                   <objectState name="name" value="red"/>
                  </not>
              </and>
                </enablement>
            </action>
        </actionSet>
    </extension>
    Dans l'exemple suivant, l'élément pluginState est utilisé pour contrôler l'activation des actions dans un ensemble d'actions. L'action Installed (A tag) est activée lorsque le plug-in avec x.y.z.myPlugin est installé. L'action Activated (B tag) est activée lorsque le même plug-in a été activé aussi.
    <extension point = "org.eclipse.ui.actionSets">
        <actionSet id="org.eclipse.ui.tests.internal.ListElementActions"
            label="List Element">
            <menu id="org.eclipse.ui.tests.internal.ListElementMenu"
                label="List Element"
                path="additions">
                <separator name="group1"/>
            </menu>
    A tag     <action id="org.eclipse.ui.tests.internal.ac8"
                label="Installed"
                menubarPath="org.eclipse.ui.tests.internal.ListElementMenu/group1"
                class="org.eclipse.ui.tests.api.MockActionDelegate">
                <enablement>
                 <pluginState id="x.y.z.myPlugin" value="installed"/>
                </enablement>
            </action>
    B tag     <action id="org.eclipse.ui.tests.internal.ac10"
                label="Activated"
                menubarPath="org.eclipse.ui.tests.internal.ListElementMenu/group1"
                class="org.eclipse.ui.tests.api.MockActionDelegate">
                <enablement>
                 <pluginState id="x.y.z.myPlugin" value="activated"/>
                </enablement>
            </action>
        </actionSet>
    </extension>
    L'exemple suivant illustre l'élément systemProperty. L'action System Property (A tag) est activée lorsque la propriété système ActionExpressionVar équivaut à "bubba".
    <extension point = "org.eclipse.ui.actionSets">
        <actionSet id="org.eclipse.ui.tests.internal.ListElementActions"
            label="List Element">
            <menu id="org.eclipse.ui.tests.internal.ListElementMenu"
                label="List Element"
                path="additions">
                <separator name="group1"/>
            </menu>
    A tag     <action id="org.eclipse.ui.tests.internal.ac11"
                label="System Property"
                menubarPath="org.eclipse.ui.tests.internal.ListElementMenu/group1"
                class="org.eclipse.ui.tests.api.MockActionDelegate">
                <enablement>
                 <systemProperty name="ActionExpressionVar" value="bubba"/>
                </enablement>
            </action>
        </actionSet>
    </extension>
    Le dernier exemple illustre la déclaration de visibilité pour une extension d'action d'un menu en incrustation. Les actions Red et True sont visibles lorsqu'un objet ListElement est sélectionné avec name = red et flag = true.
    <extension point="org.eclipse.ui.popupMenus">
        <objectContribution id="oc6"
          objectClass="org.eclipse.ui.tests.api.ListElement">
          <visibility>
             <and>
                 <objectState name="name" value="red"/>
                 <objectState name="flag" value="true"/>
             </and>
          </visibility>
          <action id="oc4" label="Red And True"
               class="org.eclipse.ui.tests.api.MockActionDelegate"/>
        </objectContribution>
    </extension>


    Implémentation fournie : Pour plus de commodité, les filtres d'action ont été définis pour les marqueurs, les ressources et les projets. Les paires name-value de chacun sont déclarées dans l'élément IMarkerActionFilter, IResourceActionFilter et IProjectActionFilter.

    Copyright IBM Corporation and others 2000, 2002.