Mandatos

Un mandato es la declaración de una acción del usuario según su id.  Los mandatos se utilizan para declarar acciones semánticas, para que las implementaciones de acciones definidas en conjuntos de acciones y editores puedan asociarse con un mandato semántico determinado.  La separación entre el mandato y la implementación de la acción permite que varios conectores definan acciones que implementan el mismo mandato semántico.  El mandato es el elemento que queda asociado con un enlace de teclas determinado.

El entorno de trabajo define muchos mandatos comunes en el archivo plugin.xml; conviene que los conectores asocien sus propias acciones a estos mandatos, siempre que ello tenga sentido.  De esta manera, las acciones similares desde el punto de vista semántico y que estén implementadas en conectores diferentes pueden compartir un mismo enlace de teclas.

Definir un mandato

Los mandatos se definen mediante el punto de extensión org.eclipse.ui.commands.  El siguiente fragmento de código procede del entorno de trabajo:

<extension
	point="org.eclipse.ui.commands">
	...
	<command
		name="%command.save.name"
		description="%command.save.description"
		categoryId="org.eclipse.ui.category.file"
		id="org.eclipse.ui.file.save">
	</command>
	...

La definición del mandato especifica un nombre (name), una descripción (description) y un id para la acción.   También especifica el ID de una una categoría para el mandato, que se utiliza para agrupar los mandatos en el diálogo de preferencias.  Las categorías también se definen en el punto de extensión org.eclipse.ui.commands:

      ...
         <category
            name="%category.file.name"
            description="%category.file.description"
            id="org.eclipse.ui.category.file">
      </category>
      ...

Tenga en cuenta que no existe ninguna implementación especificada para un mandato.  Un mandato sólo se concreta cuando un conector asocia su acción con el ID del mandato.

Asociar una acción con un mandato

Las acciones se pueden asociar a un mandato en el código o en el archivo plugin.xml de los conjuntos de acciones.  La elección depende de dónde esté definida la acción.

Las acciones cuyas instancias se crean en el código también se pueden asociar a una definición de acción mediante el protocolo IAction.  Esto se suele hacer en el momento de crear la acción.  SaveAction utiliza esta técnica cuando se autoinicializa.

public SaveAction(IWorkbenchWindow window) {
	...
	setText...
	setToolTipText...
	setImageDescriptor...
	setActionDefinitionId("org.eclipse.ui.file.save"); 
}

(Nota:  El método setActionDefinitionID debería llamarse en realidad setCommandID.  El nombre del método refleja la implementación original de los enlaces de teclas y utiliza terminología obsoleta).

Llamando a setActionDefinitionID, la acción de implementación (SaveAction) se asocia con el ID de mandato que se ha utilizado en el código de definición de mandato. Es una buena praxis definir constantes para las definiciones de acciones para que resulte fácil hacer referencia a ellas en el código.

Si define una acción de un conjunto de acciones, generalmente no necesita crear una instancia de la acción.  El entorno de trabajo lo hará automáticamente cuando el usuario llame a la acción desde un menú o desde el teclado.  En este caso, puede asociar la acción con un ID de mandato en el  código XML.  A continuación figura el código hipotético de un conjunto de acciones:

<extension point = "org.eclipse.ui.actionSets">
	   <actionSet id="com.example.actions.actionSet"
		   label="Acciones de ejemplo"
		   visible="true">
		   <action id="com.example.actions.action1"
			   menubarPath="additions"
			   label="Acción de guardar de ejemplo"
			   class="org.example.actions.ExampleActionDelegate"
			   definitionID="org.eclipse.ui.file.save">
		   </action>
		   ...
	   </actionSet>
   </extension>

El atributo definitionID sirve para declarar un id de mandato de la acción.

Mediante una de estas dos técnicas, el hecho de asociar la acción a un ID de mandato hace que los enlaces de teclas que queden definidos para el mandato org.eclipse.ui.file.save invoquen la acción en el momento oportuno. 

Veamos ahora cómo se definen los enlaces de teclas.