Menus Editeur, Barres d'outils et Actions
Identificateur : org.eclipse.ui.editorActions
Description : ce point d'extension est utilisé pour ajouter des actions au menu et à la barre d'outils d'é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.
Marques de configuration :
<!ELEMENT editorContribution (menu | action)*>
<!ATTLIST editorContribution
id
CDATA #REQUIRED
targetID CDATA #REQUIRED
>
id : identificateur unique pouvant être utilisé pour faire référence à cette contribution.
editorID : identificateur unique d'un éditeur précédemment enregistré et qui est la cible de cette contribution.
<!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 à ce menu.
-
label : libellé texte du nouveau menu. Le libellé doit contenir une mnémonique.
-
path : emplacement du menu commençant à la racine de la barre de menus.
S'il est omis, le menu est ajouté dans l'emplacement additions sur la barre de menus.
Chaque jeton du chemin d'accès doit se référer à un menu existant du plan de travail, excepté le dernier qui représente un groupe désigné du dernier menu dans le chemin d'accès.
<!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 dans le 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 la barre de menus. Le chemin d'accès peut pointer uniquement vers des menus qui appartiennent à l'éditeur cible.
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 la barre de menus.
-
toolbarPath : chemin d'accès délimité par une barre oblique (/) utilisé pour spécifier l'emplacement de l'action dans la barre d'outils. Le premier jeton représente l'ID de la barre d'outils ("Normal" correspondant à la barre d'outils par défaut), tandis que le deuxième jeton correspond au groupe désigné dans la barre d'outils.
Si le groupe n'existe pas dans la barre d'outils, il sera créé.
Si le chemin d'accès n'est pas spécifié, l'action n'apparaît pas dans la barre d'outils.
-
icon : chemin d'accès relatif d'une icône, utilisé 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, le plan de travail utilisera 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.
-
tooltip : utilisé si l'action doit figurer dans la barre d'outils. 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é.
-
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).
-
class : nom de la classe complète qui implémente org.eclipse.ui.IEditorActionDelegate.
-
enablesFor : valeur indiquant le nombre de sélections requises pour activer l'action. Si cet attribut est spécifié et que la condition est satisfaite, l'action est activée. En revanche, si elle n'est pas satisfaite, l'action est désactivée. Si aucun attribut n'est spécifié, l'action est activée pour le nombre d'options sélectionnées. 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 est 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 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 &.
-
Des raccourcis-clavier optionnels sont spécifiés à la fin du nom de la chaîne, à l'aide du caractère @, suivi de la 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 suivant est celui d'un point d'extension d'action d'éditeur :
<extension point="org.eclipse.ui.editorActions">
<editorContribution
id="com.xyz.xyzContribution"
targetID="com.ibm.XMLEditor">
<menu id="com.xyz.xyzMenu"
label="&XYZ Menu">
<separator name="group1"/>
</menu>
<action id="com.xyz.runXYZ"
label="&Run XYZ Tool"
menubarPath="com.xyz.xyzMenu/group1"
toolbarPath="Normal/XYZ"
state="true"
icon="icons/runXYZ.gif"
tooltip="Run XYZ Tool"
helpContextId="com.xyz.run_action_context"
class="com.xyz.actions.RunXYZ">
</action>
</editorContribution>
</extension>
Dans l'exemple ci-dessus, l'action spécifiée apparaît sous la forme d'une option de case à cocher dans le menu et comme bouton à bascule dans la barre d'outils.
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.IEditorActionDelegate.
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.
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 :
-
additions : représente un groupe situé sur la gauche du menu Fenêtre.
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.
Implémentation fournie : le plan de travail fournit un "éditeur de texte par défaut" intégré. Les plug-ins peuvent contribuer à cet éditeur par défaut ou à ceux fournis par d'autres plug-ins.