Ensembles 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
d'ensembles 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 est le nom unique utilisé pour identifier cet
ensemble d'actions.
-
label est le nom traduisible utilisé dans le menu
Fenêtre du plan de travail pour représenter cet ensemble jeu d'actions.
-
visible est un attribut facultatif indiquant si l'ensemble
d'actions doit être initialement visible dans toutes les
perspectives. Cette option sera uniquement respectée lorsque
l'utilisateur ouvre une nouvelle perspective ayant été
personnalisée. Il peut également remplacé cette option dans la
boîte de dialogue Personnaliser la perspective.
-
description est le sous-élément optionnel dont le corps
doit contenir un texte fournissant une brève description de l'ensemble
d'actions.
<!ELEMENT menu (separator)+ (groupMarker)*>
<!ATTLIST menu
id
CDATA #REQUIRED
label
CDATA #REQUIRED
path
CDATA #IMPLIED
>
-
id est l'identificateur unique pouvant être utilisé pour faire
référence à 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 sera ajouté avant le
menu Fenêtre dans 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 groupMarker EMPTY>
<!ATTLIST groupMarker
name
CDATA #REQUIRED
>
name est le nom du marqueur de groupe pouvant être
ensuite référencé comme dernier jeton dans le chemin d'accès à
l'action.
<!ELEMENT action (selection)* (enablement)?>
<!ATTLIST action
id
NMTOKEN #REQUIRED
label
CDATA #REQUIRED
accelerator
CDATA #IMPLIED
definitionId
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
pulldown
(true | false) #IMPLIED
class
CDATA #OPTIONAL
retarget
(true | false) #OPTIONAL
allowLabelUpdate
(true | false) #OPTIONAL
enablesFor
CDATA #IMPLIED
>
-
id est l'identificateur unique pouvant être utilisé comme
référence pour cette action.
-
label est un 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 un entier utilisé pour spécifier le code clé
du raccourci pour l'action. Il s'agit de la valeur entière résultant
d'une instruction OR au niveau du bit ou de masques de modification
de clé SWT (à savoir SWT.CTRL ou SWT.ALT) et d'un code caractères.
Par exemple, pour Ctrl+Z utilisezSWT.CTRL | 'Z' = (1<<18)|'Z' = 262234.
-
definitionId est l'ID indiqué dans le définition d'action.
Il est uniquement requis lorsqu'un ensemble d'actions spécifie des
raccourcis via le service de combinaisons de touches.
Reportez-vous aux points d'extension
Définitions d'actions
et Jeux de raccourcis
clavier.
-
menubarPath est le 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 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 le chemin d'accès n'est pas spécifié, l'action n'apparaît pas dans la barre d'outils.
-
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. L'icône
apparaît dans les barres d'outils mais pas dans les menus.
Les actions activées sont illustrées dans les menus par hoverIcon.
-
disabledIcon est un chemin relatif d'une icône utilisée pour
représenter visuellement l'action dans son contexte lorsqu'elle est
désactivé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. L'icône
désactivée apparaît dans les barres d'outils mais pas dans les menus.
Les icônes des actions désactivées dans les menu seront fournies par
le système d'exploitation.
-
hoverIcon est un chemin relatif d'une icône 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 la valeur du texte de l'infobulle 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 l'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 est utilisée comme état initial (soit true, soit false). Cet attribut est réciproquement exclusif avec pulldown.
-
pulldown est l'attribut facultatif 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 est 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".
Si l'attribut retarget a la valeur true, il ne doit pas être
fourni.
-
retarget est un attribut qui entraîne une action retarget
(globale) s'il possède la valeur true. Un gestionnaire peut être
fourni pour cette action globale à l'aide du mécanisme standard de
définition de ce type de gestionnaire avec l'ID d'action.
Si cet attribut possède la valeur true, l'attribut class ne doit pas
être fourni.
-
allowLabelUpdates s'applique uniquement si l'attribut retarget
possède la valeur true. Dans ce cas, l'actions retarget met à jour
son intitulé et l'infobulle de son gestionnaire.
-
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 est le 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 est le 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.
<!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 en
savoir plus sur l'utilisation de cet élément,
consultez le fichier actionExpressions.html.
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>
<action id="com.xyz.runABC"
label="&Run ABC Tool"
menubarPath="com.xyz.xyzMenu/group1"
toolbarPath="Normal/XYZ"
icon="icons/runABC.gif"
tooltip="Run ABC Tool"
helpContextId="com.xyz.run_abc_action_context"
retarget="true"
allowLabelUpdate="true">
</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.
Les critères d'activation pour une extension d'action sont
initialement définis par enablesFor, selection et
enablement. Toutefois, 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.
Notez que le plan de travail ne génère pas de menus à la demande
de plug-in. Les chemins de menus doit faire référence à des menus
existant déjà.
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 facultatifs sont spécifiés à la fin de la
chaîne de nom, avec @ suivi d'une série de modificateurs et
du caractère final (par exemple,
&Enregistrer@Ctrl+S). Le modificateur peut être chaîné à 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. Implémentation fournie : les plug-in peuvent utiliser ce point d'extension pour ajouter de nouveaux menus de niveau supérieur (par exemple, Débogage). Les plug-in peuvent également définir des groupes désignés qui permettent aux autres plug-in 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.
Plusieurs éléments des menus et de la barre d'outils de la fenêtre
du plan de travail sont définis par algorithme. Dans ce cas, un
mécanisme distinct doit être utilisé pour étendre la
fenêtre. Par exemple, ajoutez une nouvelle vue de plan de
travail pour faire apparaître une nouvelle option dans le
menu Fenêtre. Les extensions Importation, Exportation et Nouveaux assistants sont également ajoutées automatiquement à la fenêtre.