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-in.
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 est un identificateur unique pouvant être utilisé pour
référencer cette contribution.
editorID est l'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 est un identificateur unique pouvant être utilisé pour
référencer ce menu.
-
label est le libellé texte du nouveau menu. Le libellé doit contenir une mnémonique.
-
path est l'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 est le 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)* (enablement)?>
<!ATTLIST action
id
NMTOKEN #REQUIRED
label
CDATA #REQUIRED
accelerator
CDATA #IMPLIED
menubarPath
CDATA #IMPLIED
toolbarPath
CDATA #IMPLIED
icon
CDATA #IMPLIED
disabledIcon
CDATA #OPTIONAL
hoverIcon
CDATA #OPTIONAL
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).
-
accelerator est le raccourci clavier pour l'action. Il est
indiqué au moyen d'une combinaison des touches CTRL, MAJ et ALT et
d'une touche de raccourci.
Ces valeurs ne sont pas internationalisées et ne doivent pas être
traduites. La spécification du raccourci pour le titre de l'entrée
doit être intégrée au libellé. Elle ne sera pas utilisée pour générer
une option de menu.
-
menubarPath est un chemin absolu délimité par une barre
oblique ('/') et utilisé pour indiquer l'emplacement de l'action dans
la barre de menus. Le chemin peut uniquement désigner des menus
appartenant à 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 est le 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
toolbarPath est omis, l'action n'apparaît pas.
-
icon est le 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.
-
disabledIcon est un chemin relatif d'une icône qui sera
utilisé pour représenter visuellement l'action dans son contexte
lorsqu'elle est activée. Si ce chemin est omis, l'icône normale apparaît grisée.
Le chemin d'accès est relatif à l'emplacement du fichier plugin.xml du plug-in de contribution.
-
hoverIcon est un chemin relatif d'une icône qui sera utilisée
pour représenter visuellement l'action dans son contexte lorsque la
souris passe dessus. Si ce chemin est omis, l'icône normale sera
utilisée. Le chemin d'accès est relatif à l'emplacement du fichier plugin.xml du plug-in de contribution.
-
tooltip est utilisé si l'action doit figurer dans la
barre d'outils. Sinon, cet attribut est ignoré.
-
helpContextId est l'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 est un attribut facultatif 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 sera utilisée comme état
initial (true ou false).
-
class est le nom qualifié complet de la classe implémentant
org.eclipse.ui.IEditorActionDelegate.
-
enablesFor est la valeur indiquant le nombre de sélections
nécessaires pour activer l'action. Si cet attribut est spécifié
et que la condition est remplie, l'action est
activée. Sinon, elle reste désactivée. Si aucun attribut
n'est indiqué, l'action est activée pour tout nombre d'éléments
sélectionnés. Les formats d'attributs suivants sont pris en
charge :
! - 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.
<!ELEMENT enablement (and | or | not | objectClass
| objectState | systemProperty
| pluginState)>
<!ATTLIST enablement EMPTY>
Dans la version 2.0 d'Eclipse, un élément
enablement peut être utilisé pour définir l'activation de
l'action. Pour obtenir plus d'informations sur l'utilisation de
l'élément enablement, reportez-vous au fichier actionExpressions.html.
Les critères d'activation d'une extension d'action d'action sont initialement définis par enablesFor, selection
et enablement. 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, &Enregistrer@Ctrl+S). Les modificateurs peuvent être chaînés à l'aide du signe "+" comme délimiteur (comme dans @Ctrl+Maj+S).
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
dans le fichier plugin.xml. Ce comportement est
intuitif. Toutefois, il a été découvert qu'une fois
l'API de plateforme Eclipse figée. Si vous modifiez ce
comportement maintenant, vous endommagez chaque plug-in utilisant le
comportement existant. 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="XYZ"
label="&XYZ Menu">
<separator name="group1"/>
</menu>
<action
id="com.xyz.runXYZ"
label="&Run XYZ Tool"
menubarPath="XYZ/group1"
toolbarPath="Normal/additions"
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 cet exemple, l'action spécifiée apparaîtra sous forme de case
à cocher dans le nouveau menu de niveau supérieur nommé "XYZ Menu"
et sous forme de bouton dans la barre d'outils.
L'exemple suivant est celui d'un point d'extension d'action d'éditeur :
<extension point="org.eclipse.ui.editorActions">
<editorContribution
id="com.xyz.xyz2Contribution"
targetID="com.ibm.XMLEditor">
<menu
id="XYZ2"
label="&XYZ2 Menu"
path="edit/additions">
<separator name="group1"/>
</menu>
<action
id="com.xyz.runXYZ2"
label="&Run XYZ2 Tool"
menubarPath="edit/XYZ2/group1"
state="true"
icon="icons/runXYZ2.gif"
tooltip="Run XYZ2 Tool"
helpContextId="com.xyz.run_action_context2"
class="com.xyz.actions.RunXYZ2">
</action>
</editorContribution>
</extension>
Dans cet exemple, l'action spécifiée apparaîtra sous forme de case
à cocher dans le sous-menu nommé "XYZ2 Menu" du menu "Edit" de niveau
supérieur.
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-in peuvent contribuer à cet éditeur par défaut ou à ceux fournis par d'autres plug-in.