Jeux d'actions
Identificateur : org.eclipse.ui.actionSets
Description : ce point d'extension est utilisé pour ajouter des menus, des options de menu et des boutons de barre d'outils aux zones communes de la fenêtre du plan de travail. Ces contributions sont collectivement connues sous le nom de jeu d'actions et apparaissent dans la fenêtre du plan de travail via les préférences utilisateur.
Marques de configuration :
<!ELEMENT actionSet (menu)* (action)* (description?)>
<!ATTLIST actionSet
id CDATA
#REQUIRED
label CDATA #REQUIRED
visible (true
| false) #IMPLIED
>
<!ELEMENT description (#PCDATA)>
-
id : nom unique utilisé pour identifier ce jeu d'actions.
-
label : nom traduisible utilisé dans le menu Fenêtre du plan de travail pour représenter ce jeu d'actions.
-
visible : attribut optionnel indiquant si le jeu d'actions doit être initialement visible dans le plan de travail. L'utilisateur peut substituer cette option à partir de la boîte de dialogue "Personnalisation de la perspective".
-
description : sous-élément optionnel dont le corps doit contenir un texte fournissant une brève description du jeu d'actions.
<!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é entre les menus Perspective et Fenêtre de 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 doit représenter 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 et des sous-menus peuvent être ajoutés.
<!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
pulldown
(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. Chaque jeton du chemin d'accès, excepté le dernier, doit représenter un ID valide d'un menu existant dans 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 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 est alors 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 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.
-
tooltip : valeur du texte de l'infobulle si l'action doit figurer dans la barre d'outils. Sinon, elle est ignorée.
-
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). Cet attribut est réciproquement exclusif avec pulldown.
-
pulldown : attribut optionnel indiquant que l'action comporte un menu déroulant
supplémentaire. Si l'action apparaît dans une barre d'outils et que la valeur de l'attribut
est "true", un menu déroulant s'affiche en regard de l'action. En revanche, si
l'action apparaît dans un menu, cet attribut est ignoré. Il est réciproquement exclusif avec
state.
-
class : nom complet qualifié d'une classe qui implémente org.eclipse.ui.IWorkbenchWindowActionDelegate
ou org.eclipse.ui.IWorkbenchWindowPulldownDelegate. Cette dernière doit être implémentée dans les cas où la valeur de l'attribut pulldown est "true".
-
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 destiné au nom et 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.
Il est important de noter que le plan de travail ne génère pas de menu au nom du plug-in : les chemins d'accès au menu doivent faire référence aux menus qui existent déjà.
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 d'une série de modificateurs et du caractère final du raccourci-clavier
(par exemple, &Save@Ctrl+S). Le modificateur peut être chaîné à l'aide du signe "+" comme délimiteur (comme dans @Ctrl+Maj+S).
Exemples :
L'exemple ci-dessous décrit un jeu d'actions (notez les sous-éléments et la façon dont sont utilisés les attributs) :
<extension point = "org.eclipse.ui.actionSets">
<actionSet id="com.xyz.actionSet"
label="My Actions"
visible="true">
<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>
</actionSet>
</extension>
Dans l'exemple ci-dessus, l'action spécifiée, désignée par "My Actions", est initialement visible dans chaque perspective. Elle n'active qu'une seule sélection (l'attribut enablesFor). De plus, les objets de la sélection doivent implémenter l'interface spécifiée (IFile) et être un fichier Java.
Informations d'API : la valeur de l'attribut class doit être le nom complet qualifié d'une classe qui implémente org.eclipse.ui.IWorkbenchWindowActionDelegate
ou org.eclipse.ui.IWorkbenchWindowPulldownDelegate. Cette dernière doit être implémentée dans les cas où la valeur de l'attribut pulldown est "true". Cette classe est chargée aussi tard que possible afin d'éviter le chargement du plug-in tout entier avant que cela ne soit réellement nécessaire.
Implémentation fournie : les plug-ins peuvent utiliser ce point d'extension pour ajouter de nouveaux menus de niveau supérieur (par exemple, Débogage). Les plug-ins peuvent également définir des groupes désignés qui permettent aux autres plug-ins d'y ajouter leurs 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.
L'omission de l'attribut path entraîne l'ajout du nouveau menu au groupe de la barre de menus additions.
Les groupes par défaut dans une fenêtre du plan de travail sont définis dans l'interface IWorkbenchActionConstants. Ces constantes peuvent être utilisées dans du code pour une contribution dynamique. Les valeurs peuvent être également copiées dans un fichier XML pour une intégration étroite aux menus et à la barre d'outils existants dans le plan de travail.
Diverses options de menu et de barre d'outils dans la fenêtre du plan de travail sont définies par algorithme. Dans ce genre de cas, un mécanisme distinct peut être utilisé pour étendre la fenêtre. Par exemple, l'ajout d'une nouvelle vue du plan de travail entraîne l'affichage d'une nouvelle option dans le menu Perspective. Les extensions Importation, Exportation et Nouveaux assistants sont également ajoutées automatiquement à la fenêtre.