Este punto de extensión permite al desarrollador de plug-ins definir menús, separadores, grupos lógicos y elementos de menú que aparezcan en cualquier parte de la aplicación, desde líneas de estado hasta menús de contexto. También permite definir conjuntos de tales contribuciones (es decir, conjuntos de acciones); el usuario final puede activar o desactivar estos conjuntos de acciones. En breve, el punto de extensión de menús contiene todos los elementos de presentación (excepto los iconos) para contribuir a cualquier menú o área de ajuste de Eclipse.
A cada elemento de este punto de extensión se le otorga un identificador exclusivo. Esto se hace de tal modo que es posible hacer referencia a estos elementos en cualquier lugar sin tener que restablecer el elemento. Por ejemplo, el identificador puede ser necesario para ordenar o para definir un conjunto de acciones. Además, esto permite que los desarrolladores de plug-ins de otras empresas coloquen estos elementos en ubicaciones nuevas dentro de la interfaz, según convenga.
NOTA: en el release 3.2, la única parte de este mecanismo de extensión que se ha implementado es la parte asociada a las contribuciones de 'ajuste'. El intento de añadir elementos, menús, barras de herramientas o entradas de línea de estado actuará como NO-OP.
<!ELEMENT extension (item* , menu* , group* , widget*)>
<!ATTLIST extension
point CDATA #REQUIRED
id CDATA #IMPLIED
name CDATA #IMPLIED>
<!ELEMENT item (parameter* , location* , visibleWhen?)>
<!ATTLIST item
id CDATA #REQUIRED
commandId CDATA #REQUIRED
menuId CDATA #IMPLIED>
Un elemento puede ser un elemento de menú o un elemento de ajuste, dependiendo de dónde se coloque. El texto y la imagen asociados al elemento se trazarán desde el mandato.
org.eclipse.ui
puede llamarse org.eclipse.ui.item1
.<!ELEMENT menu (location* , visibleWhen?)>
<!ATTLIST menu
id CDATA #REQUIRED
label CDATA #IMPLIED>
Un menú puede aparecer conectado a un elemento de herramienta o en alguna parte dentro de un menú de vista, un menú de contexto o una barra de menús de nivel superior. En el caso del árbol, el desarrollador de plug-ins puede dar por supuesto que hay un menú y una barra de herramientas para cada vista y que existe la barra de menús de nivel superior. Los menús de contexto deben registrarse programáticamente para poder utilizarse (consulte la información de la API.)
Un menú solo puede contener grupos.
org.eclipse.ui
puede llamarse org.eclipse.ui.menu1
.<!ATTLIST group
id CDATA #REQUIRED
separatorsVisible (true | false) "true">
Un grupo lógico. Puede ser visible (por ejemplo, los separadores se trazan antes y después, según convenga) o invisible. Por omisión, los grupos lógicos son visibles.
Un grupo puede contener menús, elementos y otros grupos.
org.eclipse.ui
puede llamarse org.eclipse.ui.group1
.<!ELEMENT widget (location* , class? , visibleWhen? , layout?)>
<!ATTLIST widget
id CDATA #REQUIRED
class CDATA #REQUIRED>
Elemento de menú o de ajuste al que se otorga acceso directo a los widgets. Por ejemplo, esto puede utilizarse para representar un recuadro combinado. Desgraciadamente, esto significa que si un elemento de widget se hace visible en la interfaz de usuario, esto implicará la carga del plug-in. Utilice este elemento con cuidado ya que puede causar problemas de rendimiento. Esto también causará problemas para cosas como el soporte de macros, la creación de scripts y muchos otros mecanismos basados en mandatos Si se utiliza como ajuste, el widget sólo provocará la carga del plug-in cuando sea visible en la UI.
org.eclipse.ui
puede llamarse org.eclipse.ui.widget1
.IWorkbenchWidget
. Los clientes pueden optar por utilizar la implementación
predeterminada; AbstractWorkbenchTrimWidget
. Esta implementación maneja el método 'init' y pone en memoria
caché el resultado para utilizarlo a través del método getWorkbenchWindow
.<!ELEMENT layout EMPTY>
<!ATTLIST layout
fillMajor (true | false)
fillMinor (true | false) >
Este elemento puede utilizarse para especificar varias opciones de diseño para elementos añadidos en las ubicaciones de
trim
.
false
.false
.<!ELEMENT location (order? , (bar | part | popup))>
<!ATTLIST location
mnemonic CDATA #IMPLIED
imageStyle CDATA #IMPLIED>
Ubicación en la que pueden aparecer menu
, group
, item
o widget
. Este elemento se utiliza para controlar información específica de ubicación.
<!ELEMENT bar EMPTY>
<!ATTLIST bar
type (menu|trim)
path CDATA #IMPLIED>
Un elemento de hoja en una ubicación. Esto puede ser la barra de menús o el área de ajuste. Si no está calificado,
esto indica la barra de menús o el ajuste de nivel superior. Si está calificado con un elemento part
,
esto indica el menú o el ajuste de ese componente.
menu
o trim
. Si se contribuye al
menú, el elemento estará emparentado con alguna estructura de widget. En general esto significa que utilizar elementos
de widget no tiene mucho sentido y que un icono para un mandato del elemento no es estrictamente necesario. El valor
por omisión es menu
.
Si se contribuye a trim
, la barra no requerirá generalmente un mandato ni
un icono, debe rellenarse con un widget que visualice la información de ajuste.
En el ajuste, el entorno de trabajo define cinco grupos generales que corresponden a varias posiciones alrededor de la ventana:
vertical1
.'/'
como carácter separador.<!ATTLIST class
class CDATA #REQUIRED>
Un elemento de clase que soporta la sintaxis de extensión ejecutable para los elementos widget
y dynamic
.
IExecutableExtension
.<!ELEMENT visibleWhen (not | or | and | instanceof | test | systemTest | equals | count | with | resolve | adapt | iterate)>
<!ATTLIST visibleWhen
checkEnabled (true | false) "false">
Controla la visibilidad del elemento dado.
true
, no debería haber subelementos. Esto
simplemente comprueba el estado habilitado del mandato y hace que el elemento correspondiente sea visible si el mandato
está habilitado.<!ATTLIST part
id CDATA #IMPLIED
class CDATA #IMPLIED>
Un elemento en una ubicación. Esto califica la ubicación para hacer referencia a un componente de entorno de trabajo determinado. Esto puede ser una vista o un editor. La calificación puede utilizar el nombre de clase del componente (incluyendo la herencia) o puede hacer referencia al identificador para la vista o el editor.
Solo se puede especificar uno entre id
y class
.
<!ELEMENT parameter EMPTY>
<!ATTLIST parameter
name CDATA #REQUIRED
value CDATA #REQUIRED>
Un parámetro a una extensión ejecutable o un mandato, según dónde aparezca en la extensión.
<!ELEMENT order EMPTY>
<!ATTLIST order
position (start|end|before|after)
relativeTo CDATA #IMPLIED>
Controla la posición de un menú, un grupo, un elemento o un widget dentro de una ubicación determinada.
Este atributo acepta los valores siguientes: start
(poner el elemento al principio del contenedor);
end
(poner el elemento al final de su contenedor); after
(poner el elemento después del
elemento hermano cuyo ID coincide con ref
) y before
(poner el elemento antes del elemento
hermano cuyo ID coincide con ref
). El orden relativo puede aplicarse a cualquier tipo de elemento de menú.
En el caso de conflictos, Eclipse elegirá un orden arbitrario. La única garantía es que, en el caso de un conflicto, el orden permanecerá igual mientras se cumpla lo siguiente:
position
es before
o after
.<!ELEMENT popup EMPTY>
<!ATTLIST popup
id CDATA #IMPLIED
path CDATA #IMPLIED>
Parte de una ubicación. Indica que el menú, grupo, elemento o widget deben aparecer en el menú emergente.
<!ELEMENT enablement (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>
Elemento raíz genérico. El elemento puede utilizarse en un punto de extensión para definir su expresión enablement. Los hijos de una expresión de habilitación se combinan mediante el operador and.
<!ELEMENT not (not | and | or | instanceof | test | systemTest | equals | count | with | resolve | adapt | iterate)>
Este elemento representa una operación NOT en el resultado de evaluar la correspondiente expresión de subelemento.
<!ELEMENT and (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>
Este elemento representa una operación AND en el resultado de evaluar todas las expresiones de los correspondientes subelementos.
<!ELEMENT or (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>
Este elemento representa una operación OR en el resultado de evaluar todas las expresiones de subelementos.
<!ELEMENT instanceof EMPTY>
<!ATTLIST instanceof
value CDATA #REQUIRED>
Este elemento se utiliza para realizar una comprobación instanceof del objeto que tiene el foco. La expresión devuelve EvaluationResult.TRUE si el tipo del objeto es un subtipo del tipo especificado por el atributo value. De lo contrario, se devuelve EvaluationResult.FALSE.
<!ELEMENT test EMPTY>
<!ATTLIST test
property CDATA #REQUIRED
args CDATA #IMPLIED
value CDATA #IMPLIED>
Este elemento se utiliza para evaluar el estado de propiedad del objeto que tiene el foco. El conjunto de propiedades que pueden probarse puede ampliarse mediante el punto de extensión de probador de propiedades. La expresión de prueba devuelve EvaluationResult.NOT_LOADED si el probador de propiedades que realiza la prueba no se ha cargado todavía.
<!ELEMENT systemTest EMPTY>
<!ATTLIST systemTest
property CDATA #REQUIRED
value CDATA #REQUIRED>
Prueba una propiedad del sistema llamando al método System.getProperty y compara el resultado con el valor especificado con el atributo value.
<!ELEMENT equals EMPTY>
<!ATTLIST equals
value CDATA #REQUIRED>
Este elemento se utiliza para realizar una comprobación equals del objeto que tiene el foco. La expresión devuelve EvaluationResult.TRUE si el objeto es igual al valor proporcionado por el atributo value. De lo contrario, se devuelve EvaluationResult.FALSE.
<!ELEMENT count EMPTY>
<!ATTLIST count
value CDATA #REQUIRED>
Este elemento se utiliza para probar el número de elementos de una colección.
<!ELEMENT with (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>
<!ATTLIST with
variable CDATA #REQUIRED>
Este elemento cambia el objeto en el que hay que inspeccionar todos los elementos hijo para que pase a ser el objeto al que hace referencia la variable dada. Si la variable no se puede resolver, la expresión lanzará una ExpressionException al evaluarla. Los hijos de una expresión with se combinan mediante el operador and.
<!ELEMENT resolve (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>
<!ATTLIST resolve
variable CDATA #REQUIRED
args CDATA #IMPLIED>
Este elemento cambia el objeto en el que hay que inspeccionar todos los elementos hijo para que pase a ser el objeto al que hace referencia la variable dada. Si la variable no se puede resolver, la expresión lanzará una ExpressionException al evaluarla. Los hijos de una expresión with se combinan mediante el operador and.
<!ELEMENT adapt (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>
<!ATTLIST adapt
type CDATA #REQUIRED>
Este elemento se utiliza para adaptar el objeto en foco al tipo especificado por el atributo type. La expresión retorna sin cargar si el adaptador o el tipo al que se hace referencia todavía no está cargado. Se lanza una ExpressionException durante la evaluación si el nombre del tipo no existe en absoluto. Los hijos de una expresión adapt se combinan mediante el operador and.
<!ELEMENT iterate (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>
<!ATTLIST iterate
operator (or|and) >
Este elemento se usa para reiterar una variable del tipo java.util.Collection. Si el objeto que tiene el foco no es del tipo java.util.Collection, se enviará una ExpressionException al evaluar la expresión.
Una definición de menú básica tiene este aspecto.
<menu id=
"com.mycompany.myplugin.projection"
label=
"%Folding.label"
>
<location mnemonic=
"%Folding.label.mnemonic"
>
<part id=
"AntEditor"
>
<popup id=
"#RulerContext"
path=
"rest"
/>
</part>
</location>
</menu>
En este ejemplo, el desarrollador de plug-ins contribuye en todos los componentes con subclase del tipo dado o que lo implementan. Esto permite, por ejemplo, añadir algunas contribuciones a todos los editores de texto.
<menu id=
"com.mycompany.myplugin.textEditorMenu"
label=
"Text Commands"
>
<location mnemonic=
"X"
>
<part class=
"AbstractTextEditor"
>
<popup id=
"#RulerContext"
path=
"rest"
/>
</part>
</location>
</menu>
Es posible asociar la ayuda a un menú.
<menu id=
"com.mycompany.myplugin.RunWithConfigurationAction"
label=
"Run With Configuration"
helpContextId=
"run_with_configuration_context"
>
<location>
<bar />
</location>
</menu>
En un menú, es posible definir grupos lógicos. Los grupos lógicos pueden ser visibles (por ejemplo, los separadores se trazan antes y después, según convenga) o invisibles. Por omisión, los grupos lógicos son visibles.
<group id=
"com.mycompany.myplugin.stepGroup"
>
<location>
<bar path=
"org.eclipse.ui.run"
/>
</location>
</group>
<group id=
"com.mycompany.myplugin.stepIntoGroup"
separatorsVisible=
"false"
>
<location>
<bar path=
"org.eclipse.ui.run"
/>
</location>
</group>
Es posible colocar menús, grupos, elementos y widgets en varias ubicaciones.
<item id=
"com.mycompany.myplugin.ToggleStepFilters"
commandId=
"com.mycompany.myplugin.ToggleStepFilters"
>
<location mnemonic=
"%mnemonic"
>
<bar path=
"org.eclipse.ui.run/emptyStepGroup"
/>
</location>
<location>
<part id=
"org.eclipse.debug.ui.DebugView"
>
<bar type=
"trim"
path=
"renderGroup"
/>
</part>
</location>
<location mnemonic=
"%mnemonic"
>
<part id=
"org.eclipse.debug.ui.DebugView"
>
<popup path=
"renderGroup"
/>
</part>
</location>
</item>
Si el elemento emergente se especifica sin ID y sin elemento de componente padre, se aplica a cualquier menú de contexto registrado con el entorno de trabajo. Esto es parecido al comportamiento de las contribuciones de objeto antiguas. Del mismo modo, un elemento emergente de nivel superior con un ID afectará a cualquier menú de contexto registrado con el nombre dado.
<item id=
"com.mycompany.myplugin.ObjectContribution"
commandId=
"com.mycompany.myplugin.ObjectContribution"
>
<location>
<popup path=
"additions"
/>
</location>
</item>
Algunas veces, deseará controlar la visibilidad de un elemento. Mientras que normalmente es preferible mantener la
estabilidad en el diseño de menús y barras de herramientas, a veces es deseable ocultar elementos que no son relevantes
inmediatamente. Esto es particularmente cierto en menús de contexto en los que el espacio es limitado. En este caso,
definiría un elemento visibleWhen
. Este elemento es siempre idéntico a los elementos
activeWhen
y enabledWhen
definidos en el punto de
extensión de manejadores.
<item id=
"com.mycompany.myplugin.ConvertToWatchExpression"
commandId=
"com.mycompany.myplugin.ConvertToWatchExpression"
>
<location mnemonic=
"%mnemonic"
>
<part id=
"org.eclipse.debug.ui.DebugView"
>
<popup path=
"additions"
/>
</part>
</location>
<visibleWhen>
<with variable=
"selection"
>
<iterate operator=
"and"
>
<not>
<instanceof value=
"IWatchExpression"
/>
</not>
<instanceof value=
"IExpression"
/>
</iterate>
</with>
</visibleWhen>
</item>
El caso más común es simplemente hacer algo visible cuando se habilita el manejador correspondiente. Esto se maneja con
algo de azúcar sintáctica. Hay un atributo checkEnabled
en el elemento visibleWhen
.
<item id=
"com.mycompany.myplugin.compareWithPatch"
commandId=
"com.mycompany.myplugin.compareWithPatch"
>
<location mnemonic=
"%mnemonic"
>
<part id=
"MyPart"
>
<popup path=
"additions"
/>
</part>
</location>
<visibleWhen checkEnabled=
"true"
/>
</item>
Cualquier elemento asociado a un mandato puede incluir valores de parámetro. Si el parámetro del identificador dado no está definido, esto es un error. Si el elemento no tiene un mandato, esto también es un error.
<item id=
"com.mycompany.myplugin.RunHistory"
commandId=
"com.mycompany.myplugin.RunHistory"
>
<location>
<bar path=
"org.eclipse.ui.run"
/>
</location>
<parameter name=
"index"
value=
"1"
/>
</item>
También es posible especificar el orden relativo. Esto se hace utilizando el atributo de orden en el elemento de
ubicación. El atributo de orden acepta los valores siguientes: start
(poner el elemento al principio del
contenedor); end (poner el elemento al final de su contenedor); after
(poner el elemento después del
elemento hermano cuyo ID coincide con ref
) y before
(poner el elemento antes del elemento
hermano cuyo ID coincide con ref
). El orden relativo puede aplicarse a cualquier tipo de elemento de menú.
<item id=
"com.mycompany.myplugin.MyFirstItem"
commandId=
"com.mycompany.myplugin.MyFirstCommand"
>
<location>
<order position=
"start"
/>
<bar path=
"org.eclipse.ui.run"
/>
</location>
</item>
<item id=
"com.mycompany.myplugin.MySecondItem"
commandId=
"com.mycompany.myplugin.MySecondCommand"
>
<location>
<order position=
"after"
relativeTo=
"com.mycompany.myplugin.MyFirstItem"
/>
<bar path=
"org.eclipse.ui.run"
/>
</location>
</item>
Si necesita acceso directo a los widgets (por ejemplo, para representar un recuadro combinado), puede utilizar un
elemento widget
. Desgraciadamente, esto significa que si un elemento de widget se hace visible en la interfaz de
usuario, esto implicará la carga del plug-in.
<widget id=
"com.mycompany.myplugin.MyComboBoxSimple"
class=
"com.mycompany.myplugin.MyComboBox"
>
<location>
<bar type=
"trim"
path=
"myGroup"
/>
</location>
</widget>
<widget id=
"com.mycompany.myplugin.MyComboBoxParameterized1"
class=
"com.mycompany.myplugin.MyComboBox:a,b,c"
>
<location>
<bar type=
"trim"
path=
"myGroup"
/>
</location>
</widget>
<widget id=
"com.mycompany.myplugin.MyComboBoxParameterized2"
>
<class class=
"com.mycompany.myplugin.MyComboBox"
>
<parameter name=
"list"
value=
"a,b,c"
/>
<parameter name=
"selected"
value=
"c"
/>
<parameter name=
"editable"
value=
"false"
/>
</class>
<location>
<bar type=
"trim"
path=
"myGroup"
/>
</location>
</widget>
También puede utilizar widgets para contribuir al ajuste del entorno de trabajo. El ejemplo siguiente define un 'HeapStatus' que debe colocarse de forma predeterminada, inmediatamente después del ajuste de la línea de estado (es decir, en la parte inferior de la ventana del entorno de trabajo.) Consulte la descripción del elemento 'bar' para obtener más información sobre los grupos predefinidos.
Tenga en cuenta que los 'grupos' de ajustes pueden reubicarse en otras áreas de ajuste. La información de ubicación
relativeTo
dará por supuesto que se hace referencia al grupo en la posición predeterminada correspondiente
al determinar la nueva ubicación del ajuste. Por lo general se espera que los contribuyentes de este tipo creen su
propio grupo para albergar el widget nuevo, permitiendo que elemento de ajuste se reubique independientemente de los
otros elementos de ajuste. Una excepción notable a esto es el grupo 'status'.
<extension point=
"org.eclipse.ui.menus"
>
<group id=
"TestTrimAPI.heapStatusGroup"
separatorsVisible=
"true"
>
<location>
<bar type=
"trim"
/>
<order position=
"after"
relativeTo=
"status"
/>
</location>
</group>
<widget class=
"HeapStatusWidget"
id=
"TestTrimAPI.HeapStatus"
>
<location>
<bar path=
"heapStatusGroup"
type=
"trim"
/>
</location>
<layout fillMajor=
"false"
fillMinor=
"true"
/>
</widget>
</extension>
IWorkbenchPartSite.registerContextMenu
.
Copyright (c) 2005 IBM Corporation y otros.
Reservados todos los derechos. Este programa y sus materiales adjuntos están
disponibles bajo los términos de la licencia pública común (Eclipse Public
License) v1.0 que acompaña a esta distribución, y está disponible en http://www.eclipse.org/legal/epl-v10.html