Gestionnaires

org.eclipse.ui.handlers

3.1

Le point d'extension des gestionnaires est une élaboration de l'élément expérimental handlerSubmission défini dans Eclipse 3.0. Un gestionnaire est le comportement d'une commande à un moment donné. Une commande peut avoir zéro ou plusieurs gestionnaires associés. Cependant, une commande aura zéro ou un gestionnaire actif pour un instant donné. Le gestionnaire actif est celui actuellement responsable de l'exécution du comportement de la commande. Cela est très similaire au concept des gestionnaires d'actions et des actions redirigeables.

Le point d'extension des gestionnaires permet à un développeur de plug-in de définir un gestionnaire devenant actif et/ou étant activé dans certaines conditions. Si un gestionnaire est inactif, alors aucune commande ne déléguera son comportement. Si un gestionnaire est inactivé, aucune exécution ne lui sera demandé; l'exécution du gestionnaire est bloquée. Les conditions sont définies à l'aide de la fonction de langage d'expressions ajoutée dans la version 3.0. Elles sont énoncées à l'aide des clauses activeWhen et enabledWhen.

Le plan de travail fournit des variables sur lesquelles ces expressions peuvent s'appuyer. Les variables acceptées sont : les contextes actifs, l'éditeur et le composant actif ainsi que la sélection courante. Non prises en charge par la conception initiale, il est facile d'imaginer comment rendre possible l'ajout d'autres variables et comment permettre aux développeurs de plugs-in d'en créer d'autres.

Un gestionnaire pour lequel aucune condition n'a été définie est un gestionnaire par défaut. Un gestionnaire par défaut est actif uniquement lorsqu'aucun autre gestionnaire n'a vu ses conditions satisfaites. Si deux gestionnaires voient leurs conditions satisfaites, celles-ci sont alors comparées. Le gestionnaire sélectionné sera celui dont les conditions sont plus spécifiques ou les plus locales. Pour cela, les variables auxquelles la condition fait référence sont examinées. La condition faisant référence à la variable la plus spécifique est "gagnante". L'ordre de spécificité (du moins spécifique au plus spécifique) est défini dans org.eclipse.ui.ISources.

Si cela ne suffit pas à résoudre le conflit, aucun gestionnaire n'est actif. Si une option de trace particulière est lancée, un message apparaît dans le fichier journal. Il y a également conflit lorsqu'il existe deux gestionnaires par défaut. Il est de la responsabilité des développeurs de plugs-in et des testeurs d'intégration de s'assurer que cela n'arrive pas. Ces conditions servent à éviter le chargement de plugs-in inutiles. Ces définitions de gestionnaire sont encapsulées dans un proxy. Pour qu'un proxy puisse charger le gestionnaire sous-jacent, il faut que : les conditions du proxy soient respectées afin que celui-ci devienne actif et que la commande ait une action à déléguer (par exemple, execute()).

<!ELEMENT extension (handler)>

<!ATTLIST extension

point CDATA #REQUIRED

id    CDATA #IMPLIED

name  CDATA #IMPLIED>


<!ELEMENT handler (activeWhen? | class? | enabledWhen?)>

<!ATTLIST handler

commandId CDATA #REQUIRED

class     CDATA #IMPLIED>


<!ELEMENT activeWhen (not | and | or | instanceof | test | systemTest | equals | count | with | resolve | adapt | iterate)>



<!ELEMENT enabledWhen (not | and | or | instanceof | test | systemTest | equals | count | with | resolve | adapt | iterate)>



<!ELEMENT class (parameter)>

<!ATTLIST class

class CDATA #IMPLIED>


<!ELEMENT parameter EMPTY>

<!ATTLIST parameter

name  CDATA #REQUIRED

value CDATA #REQUIRED>


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



<extension point=

"org.eclipse.ui.handlers"

>

<handler commandId=

"commandId"

class=

"org.eclipse.compare.Command"

>

<activeWhen>

<with variable=

"selection"

>

<count value=

"1"

/>

<iterate operator=

"and"

>

<adapt type=

"IResource"

/>

</iterate>

</with>

</activeWhen>

</handler>

</extension>

Pour éviter le chargement de plugs-in supplémentaires, il est possible de définir à quel moment le gestionnaire a été activé. Si le proxy n'a pas encore chargé le gestionnaire, alors seule la syntaxe des expressions sert à décider si le gestionnaire est activé ou non. Si le proxy a chargé le gestionnaire, on commence par prendre en compte la syntaxe des expressions. Si la syntaxe des expressions a pour résultat "true", on interroge le gestionnaire pour savoir s'il est activé. (S'il existe une opération booléenne "and" en court-circuit entre la syntaxe des expressions et l'état activé du gestionnaire.)

<extension point=

"org.eclipse.ui.handlers"

>

<handler commandId=

"commandId"

class=

"org.eclipse.Handler"

>

<enabledWhen>

<with variable=

"context"

>

<property id=

"id"

value=

"debugging"

/>

</with>

</enabledWhen>

</handler>

</extension>

Tous les gestionnaires implémentent org.eclipse.core.commands.IHandler. Il est possible d'activer ou de désactiver les gestionnaires par le biais de l'interface org.eclipse.ui.handlers.IHandlerService. Cette interface peut être récupérée à partir des objets du plan de travail la prenant en charge, tels que le IWorkbench lui-même. Pour récupérer ce service, lancez un appel tel que IWorkbench.getAdapter(IHandlerService.class).

Il est également possible d'activer ou de désactiver les gestionnaires à l'aide du code hérité dans le plan de travail. Cette opération peut être effectuée via le mécanisme existant ci-dessous. Ce mécanisme est utile aux clients utilisant des actions pour enrichir les menus ou les barres de menus.

 IWorkbenchPartSite mySite;
 IAction myAction;
 
 myAction.setActionDefinitionId(commandId);
 IKeyBindingService service = mySite.getKeyBindingService();
 service.registerAction(myAction);