Menus Vue, Barres d'outils et Actions
Identificateur : org.eclipse.ui.viewActions
Description : ce point d'extension est utilisé pour ajouter des actions au menu et à la barre d'outils pour les vues enregistrées par d'autres plug-ins.
Chaque vue comporte un menu déroulant local que l'on active normalement en cliquant dans la zone supérieure droite. D'autres plug-ins peuvent ajouter des sous-menus et des actions à ce menu.
Les plug-ins peuvent également ajouter des actions à la barre d'outils d'une vue.
Les propriétaires de vue reçoivent en premier l'opportunité de remplir ces zones.
Des ajouts optionnels sont réalisés par d'autres plug-ins.
Marques de configuration :
<!ELEMENT viewContribution (menu | action)*>
<!ATTLIST viewContribution
id
CDATA #REQUIRED
targetID CDATA #REQUIRED
>
id : identificateur unique pouvant être utilisé pour faire référence à la contribution.
targetID : identificateur unique de la vue (comme spécifié dans le registre) dans lequel la contribution est réalisée.
<!ELEMENT menu (separator)+>
<!ATTLIST menu
id
CDATA #REQUIRED
label
CDATA #REQUIRED
path
CDATA #IMPLIED
>
-
id : identificateur unique pouvant être utilisé pour faire référence au menu.
-
label : libellé texte du nouveau menu. Le libellé doit contenir une mnémonique.
-
path : emplacement du menu commençant à partir du menu déroulant, le dernier jeton représentant le groupe nommé. S'il est omis, le menu est ajouté à la fin du menu en déroulant.
<!ELEMENT separator EMPTY>
<!ATTLIST separator
name
CDATA #REQUIRED
>
name : nom du séparateur auquel il peut être ultérieurement fait référence en tant que dernier jeton du chemin d'accès de l'action. De ce fait, les séparateurs servent de groupes désignés dans lesquels des actions peuvent être ajoutées.
<!ELEMENT action (selection)*>
<!ATTLIST action
id
NMTOKEN #REQUIRED
label
CDATA #REQUIRED
menubarPath
CDATA #IMPLIED
toolbarPath
CDATA #IMPLIED
icon
CDATA #IMPLIED
tooltip
CDATA #IMPLIED
helpContextId
CDATA #IMPLIED
state
(true | false) #IMPLIED
class
CDATA #REQUIRED
enablesFor
CDATA #IMPLIED
>
-
id : identificateur unique pouvant être utilisé comme référence pour cette action.
-
label : nom traduisible utilisé de diverses façons, en fonction du contexte.
Dans les menus, il est utilisé comme texte de menu. Dans les barres d'outils, il est utilisé comme libellé de bouton. Le libellé peut contenir une mnémonique et un raccourci-clavier codé JFace (voir l'exemple).
-
menubarPath : chemin d'accès délimité par une barre oblique (/) utilisé pour spécifier l'emplacement de l'action dans le menu déroulant. Chaque jeton du chemin d'accès, excepté le dernier, représente un menu existant de la hiérarchie.
Le dernier jeton représente le groupe séparateur désigné dans lequel l'action est ajoutée.
Si le chemin d'accès n'est pas spécifié, l'action n'apparaît pas dans le menu déroulant.
-
toolbarPath : groupe désigné dans la barre d'outils locale de la vue cible.
Si le groupe n'existe pas, il est créé. S'il est omis, l'action n'apparaît pas dans la barre d'outils locale.
-
icon : chemin d'accès relatif pour une icône utilisée pour représenter visuellement l'action dans son contexte. S'il est omis alors que l'action doit apparaître dans la barre d'outils locale, le plan de travail utilise une icône de marque de réservation.
Le chemin d'accès est relatif à l'emplacement du fichier plugin.xml du plug-in de contribution.
-
state : attribut optionnel indiquant que l'action doit être d'un type à bascule. Une fois ajouté au menu, il se manifeste sous la forme d'une option de case à cocher. Une fois ajouté à la barre d'outils, il devient bouton à bascule. S'il est défini, la valeur de l'attribut est utilisée comme état initial (soit true, soit false).
-
tooltip : utilisé si l'action doit figurer dans la barre d'outils locale. Sinon, cet attribut est ignoré.
-
helpContextId : identificateur unique indiquant l'ID contextuel de l'aide pour cette action. Si l'action apparaît comme option de menu, l'activation de la touche F1 pendant la mise en évidence de l'option de menu entraîne l'affichage de l'aide correspondant à l'ID du contexte donné.
-
class : nom de la classe complète qui implémente org.eclipse.ui.IViewActionDelegate.
-
enablesFor : valeur indiquant le nombre de sélections nécessaires pour activer l'action. Si cet attribut est spécifié et que la condition est satisfaite, l'action est activée. Dans le cas contraire, elle est désactivée. Si aucun attribut n'est spécifié, l'action est activée quel que soit le nombre d'éléments sélectionnés. Les formats d'attribut suivants sont supportés :
! - aucun élément sélectionné
? - aucun ou un élément sélectionné
+ - un ou plusieurs éléments sélectionnés
multiple, 2+ - deux ou plusieurs éléments sélectionnés
n - nombre précis d'éléments sélectionnés, par exemple : 4.
* - n'importe quel nombre d'éléments sélectionnés
<!ELEMENT selection EMPTY>
<!ATTLIST selection
class
CDATA #REQUIRED
name
CDATA #IMPLIED
>
-
class : nom complet qualifié de la classe ou de l'interface que chaque objet de la sélection doit sous-classer ou implémenter afin d'activer l'action.
-
name : filtre générique qui peut être éventuellement appliqué aux objets de la sélection. Si ce filtre est spécifié et que la correspondance échoue, l'action sera désactivée.
Les critères d'activation pour une extension d'action sont initialement définis par enablesFor et selection. 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 et les raccourcis-clavier en respectant les règles suivantes :
-
Les mnémoniques sont spécifiées à l'aide du caractère perluète (&) placé devant un caractère mnémonique dans le texte traduisible.
Comme le caractère perluète n'est pas autorisé dans les chaînes XML, utilisez l'entité de caractère &.
-
Des raccourcis-clavier optionnels sont spécifiés à la fin du nom de la chaîne, à l'aide du caractère @, suivi d'une série de modificateurs et du caractère final du raccourci-clavier
(par exemple, &Save@Ctrl+S). Les modificateurs peuvent être chaînés à l'aide du signe "+" comme délimiteur (comme dans @Ctrl+Maj+S).
Exemples :
L'exemple ci-dessous décrit un point d'extension d'actions de vue (notez les sous-éléments et la façon dont sont utilisés les attributs) :
<extension point="org.eclipse.ui.viewActions">
<viewContribution
id="com.xyz.xyzViewC1"
targetID="org.eclipse.ui.views.navigator.ResourceNavigator">
<menu id="com.xyz.xyzMenu"
label="XYZ Menu"
path="additions">
<separator name="group1"/>
</menu>
<action id="com.xyz.runXYZ"
label="&Run XYZ Tool"
menubarPath="com.xyz.xyzMenu/group1"
toolbarPath="Normal/XYZ"
icon="icons/runXYZ.gif"
tooltip="Run XYZ Tool"
helpContextId="com.xyz.run_action_context"
class="com.xyz.actions.RunXYZ"
enablesFor="1"/>
<selection class="org.eclipse.core.resources.IFile" name="*.java">
</action>
</viewContribution>
</extension>
Dans l'exemple ci-dessus, l'action spécifiée n'active qu'une seule sélection (l'attribut enablesFor). De plus, chaque objet de la sélection doit implémenter l'interface spécifiée (IFile) et être un fichier Java. Plusieurs éléments selection peuvent être spécifiés, signifiant "l'un de".
Informations d'API : la valeur de l'attribut class doit être un nom complet qualifié d'une classe Java qui implémente org.eclipse.ui.IViewActionDelegate.
Cette interface 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.
Elle étend org.eclipse.ui.IActionDelegate et ajoute une méthode supplémentaire qui permet au délégué de s'initialiser avec la nouvelle instance à laquelle elle contribue.
Implémentation fournie : chaque vue est généralement fournie avec un certain nombre d'options standard dans le menu déroulant et la barre d'outils locale.
Les ajouts émanant d'autres plug-ins sont annexés au complément standard. Il est utile de publier les identificateurs d'action pour une vue dans une interface publique. Par exemple, les actions et les groupes majeurs destinés à la fenêtre du plan de travail sont définis dans org.eclipse.ui.IWorkbenchActionConstants.