Descripción: este punto de extensión permite añadir acciones nuevas a los menús emergentes que sean propiedad de otros conectores. La contribución de acciones se puede hacer con respecto a un tipo de objeto específico (objectContribution) o con respecto a un menú emergente específico. Cuando esté registrada para un tipo de objeto, la contribución aparecerá en todos los visores en los que estén seleccionados objetos del tipo especificado. Por el contrario, si está registrada para un menú emergente, únicamente aparecerá en el menú especificado, sin tener en cuenta la selección.
Cuando la selección es heterogénea, la contribución se aplicará si está registrada con respecto a un tipo común de la selección, si es posible. Si no es posible una coincidencia directa, se intentará con respecto a las superclases y a las superinterfaces.
La selección se puede restringir adicionalmente si se utiliza un filtro de nombres. En tal caso, todos los objetos de la selección deben coincidir con el filtro para que se aplique la contribución.
En una contribución de objeto, las acciones individuales pueden utilizar el atributo enablesFor para especificar si solamente debe aplicarse para una selección individual, múltiple o para cualquier otro tipo de selección.
Si estos mecanismos de filtrado son inadecuados, la contribución de acciones puede utilizar el mecanismo filter. En este caso, los atributos del objeto destino se describen en una serie de pares de clave-valor. Los atributos aplicables a la selección son específicos del tipo y sobrepasan el dominio del propio entorno de trabajo, por lo que este delegará el filtrado a este nivel a la selección real.
Códigos XML de configuración:
<!ELEMENT objectContribution (filter | menu | action)*
(visibility)?>
<!ATTLIST objectContribution
id
CDATA #REQUIRED
objectClass CDATA #REQUIRED
nameFilter CDATA #IMPLIED
adaptable (true|false)
#IMPLIED
>
En la versión 2.0 de Eclipse, puede usarse un elemento visibility en una objectContribution para definir la visibilidad de la acción. No se trata de una sustitución del atributo objectClass, que define el destino primario de la acción. El elemento visibility sirve para definir con más precisión el destino primario. Hallará más información sobre la utilización del elemento visibility en actionExpressions.html.<!ELEMENT viewerContribution (menu | action)*>
<!ELEMENT action (selection)* (enablement)?>name: nombre del separador al que más adelante se puede hacer referencia como último símbolo de la vía de acceso de la acción. Por lo tanto, los separadores actúan a modo de grupos con nombre a los que pueden añadirse acciones.
En la versión 2.0 de Eclipse, puede usarse un elemento enablement para definir la habilitación de la acción. Hallará más información sobre cómo utilizar el elemento enablement en actionExpressions.html.Los criterios de habilitación de una extensión de acciones se definen inicialmente con los atributos enablesFor, selection y enablement. Sin embargo, una vez creada una instancia del delegado de la acción, dicha instancia puede controlar el estado de habilitación de la acción directamente dentro del correspondiente método selectionChanged.
Las etiquetas de acción y de menú pueden contener caracteres especiales que codifican nemotécnicos, que se especifican utilizando el carácter & delante de un carácter seleccionado del texto traducido. Como el símbolo ampersand no está permitido en las series XML, hay que utilizar la entidad de tipo carácter &.
Si se contribuye suministrando dos o más acciones a un menú o barra de herramientas mediante una extensión individual, las acciones aparecerán en el orden inverso de como figuran en el archivo plugin.xml. Este comportamiento es definitivamente poco intuitivo. No obstante, se descubrió después de haber congelado la API de la plataforma Eclipse. Si se cambiara ahora el comportamiento, quedarían dañados todos los conectores que se basan en el comportamiento existente.
Ejemplos:
A continuación figura un ejemplo de punto de extensión de un menú emergente:
<extension point="org.eclipse.ui.popupMenus">
<objectContribution
id="com.xyz.C1"
objectClass="org.eclipse.core.resources.IFile"
nameFilter="*.java">
<menu id="com.xyz.xyzMenu"
path="additions"
label="&Herramientas Java XYZ">
<separator name="group1"/>
</menu>
<action id="com.xyz.runXYZ"
label="&Ejecutar herramienta XYZ"
menubarPath="com.xyz.xyzMenu/group1"
icon="icons/runXYZ.gif"
helpContextId="com.xyz.run_action_context"
class="com.xyz.actions.XYZToolActionDelegate"
enablesFor="1">
</action>
</objectContribution>
<viewerContribution
id="com.xyz.C2"
targetID="org.eclipse.ui.views.TaskList">
<action
id="com.xyz.showXYZ"
label="&Mostrar XYZ"
menubarPath="additions"
icon="icons/showXYZ.gif"
helpContextId="com.xyz.show_action_context"
class="com.xyz.actions.XYZShowActionDelegate">
</action>
</viewerContribution>
</extension>
En el ejemplo anterior, la acción especificada solo se habilitará para una selección individual (atributo enablesFor). Además, cada objeto de la selección debe implementar la interfaz especificada (IFile) y tiene que ser un archivo Java. Esta acción se añadirá a un submenú creado anteriormente. Esta contribución entrará en vigor en cualquier vista que tenga la selección necesaria.
Por el contrario, la contribución de visor anterior únicamente aparecerá en la vista Tareas, y no se verá afectada por la selección que haya en la vista.
A continuación figura un ejemplo del mecanismo de filtro. En este caso, la acción únicamente aparecerá para los IMarkers que se hayan completado y tengan alta prioridad.
<extension point="org.eclipse.ui.popupMenus">
<objectContribution
id="com.xyz.C1"
objectClass="org.eclipse.core.resources.IMarker">
<filter name="done"
value="true"/>
<filter name="priority"
value="2"/>
<action id="com.xyz.runXYZ"
label="Herramienta de acciones completadas de alta prioridad"
icon="icons/runXYZ.gif"
class="com.xyz.actions.MarkerActionDelegate">
</action>
</objectContribution>
</extension>
Información sobre las API: el valor del atributo class de la acción debe ser un nombre totalmente calificado de una clase Java que implemente org.eclipse.ui.IObjectActionDelegate, en el caso las contribuciones de objeto, org.eclipse.ui.IViewActionDelegate, para las contribuciones a visores que pertenezcan a vistas, o org.eclipse.ui.IEditorActionDelegate para las contribuciones a visores que pertenezcan a editores. En todos los casos, la clase implementante se carga lo más tarde posible para evitar que se cargue todo el conector antes de que sea realmente necesario.
Nota: para la compatibilidad con versiones anteriores, hay que implementar org.eclipse.ui.IActionDelegate para las contribuciones de objeto.
La extensión de un menú emergente dentro de un componente solo es posible cuando el componente destino publica un menú para la extensión. Se anima encarecidamente a que se haga así, porque mejora la ampliabilidad del producto. Para lograrlo, cada componente debe publicar los menús emergentes que estén definidos, llamando a IWorkbenchPartSite#registerContextMenu. Una vez hecho esto, el entorno de trabajo insertará automáticamente las extensiones de acciones que existan.
Debe proporcionarse un ID de menú para cada menú registrado. Por cuestión de coherencia en los componentes, todos los implementadores de componentes deben adoptar la estrategia siguiente:
Un objeto del entorno de trabajo que sea la selección en un menú contextual puede definir un org.eclipse.ui.IActionFilter. Esta es una estrategia de filtrado que puede realizar un filtrado específico del tipo. El entorno de trabajo recuperará el filtro para la selección comprobando si implementa IActionFilter. Si esto falla, el entorno de trabajo solicitará un filtro mediante el mecanismo IAdaptable.
Implementación suministrada: las vistas del entorno de trabajo tienen menús emergentes incorporados que ya vienen cargados con varias acciones. Los conectores pueden suministrar contribuciones a estos menús. Si una vista tiene espacios reservados para estas contribuciones y se hacen públicos, los nombres de los espacios pueden utilizarse como vías de acceso. En caso contrario, las acciones y los submenús se añadirán al final del menú emergente.