Versión 3.2
Este documento describe la estructura del archivo de contenido de hoja de apuntes como una serie de fragmentos DTD (esquema XML legible por máquina).
cheatsheet
<!ELEMENT cheatsheet (intro, item+)> <!ATTLIST cheatsheet title CDATA #REQUIRED >
El elemento <cheatsheet> define el cuerpo del archivo de contenido de hoja de apuntes. Los atributos de <cheatsheet> son los siguientes:
intro
<!ELEMENT intro (description)> <!ATTLIST intro contextId CDATA #IMPLIED href CDATA #IMPLIED >
El elemento <intro> se utiliza para describir la introducción de hoja de apuntes que debe visualizarse. El subelemento <description> contiene el cuerpo de la introducción. Los atributos de <intro> son los siguientes:
description
<!ELEMENT description EMPTY> <!ATTLIST description >
El elemento <description> contiene la descripción de una hoja de apuntes o de un elemento de la misma. La descripción consta de texto mezclado con códigos de formato simples. La hoja de apuntes formatea y diseña automáticamente el texto para que se muestre correctamente en la UI. Dentro del texto, los códigos <b>...</b> de inicio y final hacen que el texto que se encuentra entre ellos se visualice en negrita, y puede utilizarse el elemento <br/> para forzar un salto de línea. Estos son los únicos códigos de formato soportados en este momento (sin embargo, puede que se añadan otros en el futuro). Determinados caracteres del texto tienen un significado especial para los analizadores XML; en particular, en lugar de escribir "<", ">", "&", "'" y """ (comillas), escriba "<", ">", "&", "'" y """, respectivamente. Los espacios en blanco (espacios y saltos de línea) se tratan como separadores de palabras; los espacios adyacentes y saltos de línea se tratan como una sola unidad y se visualizan como un solo espacio o un salto de línea. Los espacios en blanco situados inmediatamente después de los códigos <description> y <br/> se pasan por alto, igual que los espacios en blanco inmediatamente anteriores al código </description>.
item
<!ELEMENT item (description ([action|command|perform-when] | (subitem|repeated-subitem|conditional-subitem)*) [onCompletion])> <!ATTLIST item title CDATA #REQUIRED dialog ("true" | "false") "false" skip ("true" | "false") "false" contextId CDATA #IMPLIED href CDATA #IMPLIED >
Cada elemento <item> describe un paso del nivel más alto de una hoja de apuntes. Un <item> puede contener elementos <subitem>. Los atributos de <item> son los siguientes:
El punto de extensión org.eclipse.ui.cheatsheets.cheatSheetItemExtension permite visualizar controles personalizados opcionales del elemento en la UI. Las contribuciones a este punto de extensión declaran los nombres de atributos adicionales con valor de serie que pueden aparecer en elementos <item>.
Los elementos item tienen una descripción y una acción o mandato opcionales. En la presentación típica, los títulos de los elementos de la hoja de apuntes se muestran al usuario la mayor parte del tiempo. La descripción de un elemento sólo se muestra mientras el paso está en proceso de ejecución. La presencia de un elemento <action>, <command> or <perform-when>) está asociada a un botón que el usuario puede pulsar para realizar la acción o el mandato del paso. Si no hay ninguna acción ni ningún mandato, el usuario debe llevar a cabo el paso manualmente y, a continuación, indicar explícitamente que lo ha realizado satisfactoriamente.
Los pasos pueden dividirse en subpasos según lo especificado por los subelementos <subitem>. A diferencia de los elementos, que el usuario debe seguir por estricto orden, los subelementos de un elemento determinado pueden ejecutarse en cualquier orden. Todos los subelementos de un elemento deben intentarse (o saltarse) antes de continuar con el elemento siguiente. (Lo que significa que las acciones que deben realizarse en un orden obligatorio no pueden representarse como subelementos).
Un subelemento <conditional-subitem> permite a un paso adaptar la presentación de un subpaso en función de variables de hoja de apuntes cuyos valores se adquieren en pasos anteriores. Un subelemento <repeated-subitem> permite a un paso incluir un conjunto de subpasos similares. De nuevo, el conjunto exacto de subpasos puede basarse en variables de hoja de apuntes cuyos valores se adquieren en pasos anteriores.
subitem
<!ELEMENT subitem ( [action|command|perform-when] )> <!ATTLIST subitem label CDATA #REQUIRED skip ("true" | "false") "false" when CDATA #IMPLIED >
Cada elemento <subitem> describe un subpaso de una hoja de apuntes. Un <subitem> transporta una etiqueta de texto simple, pero no tiene una descripción larga ni más subelementos. Los atributos de <subitem> son los siguientes:
Los subelementos pueden tener una acción o un mandato opcionales. La presencia de un elemento <action>, <command> o <perform-when> está asociada normalmente a un botón que el usuario puede pulsar para realizar el mandato o la acción del subpaso. Si no hay ninguna acción ni ningún mandato, el usuario debe llevar a cabo el subpaso manualmente y, a continuación, indicar explícitamente que lo ha realizado satisfactoriamente.
A diferencia de los elementos, que deben seguirse por estricto orden, los subelementos de un elemento determinado pueden ejecutarse en cualquier orden. Todos los subelementos de un elemento deben realizarse o saltarse antes de continuar con el elemento siguiente. (Lo que significa que las acciones que deben realizarse en un orden obligatorio no deben representarse como subelementos).
conditional-subitem
<!ELEMENT conditional-subitem (subitem+)> <!ATTLIST conditional-subitem condition CDATA #REQUIRED >
Cada elemento <conditional-subitem> describe un solo subpaso cuyo formato puede diferir en función de una condición conocida en el momento de expandir el elemento. Los atributos de <conditional-subitem> son los siguientes:
El atributo condition del elemento <conditional-subitem> proporciona un valor de serie (invariablemente este valor proviene de una variable de hoja de apuntes). Cada uno de los hijos de <subitem> debe transportar un atributo when con un valor de serie distintivo. Cuando se expande el elemento, el elemento <conditional-subitem> se sustituye por el elemento <subitem> con el valor coincidente. Si no hay ningún elemento <subitem> con un valor coincidente, se considera un error.
Por ejemplo, si la variable de hoja de apuntes llamada "v1" tiene el valor "b" cuando se expande el siguiente elemento
<item ...> <conditional-subitem condition="${v1}"> <subitem when="a" label="Step for A." /> <subitem when="b" label="Step for B." /> </conditional-subitem> </item>se selecciona el segundo subelemento y el elemento se expande en algo equivalente a
<item ...> <subitem label="Step for B."/> </item>
repeated-subitem
<!ELEMENT repeated-subitem (subitem)> <!ATTLIST repeated-subitem values CDATA #REQUIRED >
Cada elemento <repeated-subitem> describe un subelemento que se expande en 0, 1 o subpasos más similares. Los atributos de <repeated-subitem> son los siguientes:
El atributo values proporciona una lista de series separadas por comas; el hijo de <subitem> suministra la plantilla. Cuando se expande el elemento, el elemento <repeated-subitem> se sustituye por las copias del elemento <subitem> con las apariciones de la variable "this" sustituidas por el valor de serie correspondiente.
Por ejemplo, si la variable de hoja de apuntes llamada "v1" tiene el valor "1,b,three" cuando se expande el siguiente elemento
<item ...> <repeated-subitem values="${v1}"> <subitem label="Step ${this}."> <action class="com.xyz.myaction" pluginId="com.xyz" param1="${this}"/> </subitem> </repeated-subitem> </item>el elemento se expande en algo equivalente a:
<item ...> <subitem label="Step 1."> <action class="com.xyz.myaction" pluginId="com.xyz" param1="1"/> </subitem> <subitem label="Step b."> <action class="com.xyz.myaction" pluginId="com.xyz" param1="b"/> </subitem> <subitem label="Step three."> <action class="com.xyz.myaction" pluginId="com.xyz" param1="three"/> </subitem> </item>
action
<!ELEMENT action EMPTY> <!ATTLIST action class CDATA #REQUIRED pluginId CDATA #REQUIRED param1 CDATA #IMPLIED ... param9 CDATA #IMPLIED confirm ("true" | "false") "false" when CDATA #IMPLIED >
Cada elemento <action> describe una acción de una hoja de apuntes. Los atributos de <action> son los siguientes:
org.eclipse.jface.action.IAction
.
Si esta acción también implementa
org.eclipse.ui.cheatsheets.ICheatSheetAction
, se invocará por medio de su método
run(String[],ICheatSheetManager) y se le pasarán el gestor de hojas de apuntes y los parámetros de acción. El atributo pluginId debe estar presente siempre que esté presente este atributo. Es muy aconsejable que las acciones que esté previsto invocar desde hojas de apuntes notifiquen una salida satisfactoria/anómala si la ejecución de la acción puede fallar (quizás debido a que el usuario la acción desde su diálogo). (Consulte
org.eclipse.jface.action.Action.notifyResult(boolean) para obtener detalles).org.eclipse.ui.cheatsheets.ICheatSheetAction
, los valores de serie de estos atributos se pasan a la acción cuando se invoca. Puede pasar hasta 9 parámetros a una acción de hoja de apuntes (param1,
param2, etc.). Los parámetros suministrados deben empezar por el parámetro 1 y ser contiguos; es decir, es ilegal especificar parám2 sin que el parám1 también esté presente. Si la serie del atributo tiene el formato
"${var}", se considera una referencia a una variable de hoja de apuntes
var, y el valor de la condición será el valor de la variable de la hoja de apuntes al principio de la ejecución del elemento <item> contenedor (o la serie vacía si la variable no está enlazada en ese momento).command
<!ELEMENT command EMPTY> <!ATTLIST command serialization CDATA #REQUIRED returns CDATA #IMPLIED confirm ("true" | "false") "false" when CDATA #IMPLIED >
Cada elemento <command> describe un mandato de una hoja de apuntes. Los atributos de <command> son los siguientes:
A continuación se proporciona un ejemplo de un elemento item con un mandato que abre un recuadro de diálogo y almacena el resultado en la variable de la hoja de apuntes "result".
<item title="Selección de vista"> <description>Seleccionar una vista que se abrirá en el paso siguiente.</description> <command returns = "result" serialization="org.eclipse.ui.dialogs.openMessageDialog(title=Seleccionar vista,buttonLabel0=Explorador de paquetes,message=Seleccionar una vista ,buttonLabel1=Buscar vista)"/> <onCompletion> Se ha seleccionado la ${result}. </onCompletion> </item>
onCompletion
<!ELEMENT onCompletion EMPTY> <!ATTLIST onCompletion >
El elemento <onCompletion> contiene texto que se visualizará cuando se realice un elemento item. Esto resulta particularmente útil en el paso final de la hoja de apuntes para reconocer la realización de toda la tarea. La descripción consiste en texto mezclado con códigos de formato simples que sigue las mismas reglas que para un elemento <description>. Los elementos <onCompletion> también pueden contener referencias a las variables de hoja de apuntes de la forma "${var}" que se expandirán utilizando el valor real de la variable de la hoja de apuntes var en el momento de realizar este paso.
perform-when
<!ELEMENT perform-when ((action|command)+)> <!ATTLIST perform-when condition CDATA #REQUIRED >
Cada elemento <perform-when> describe una acción de una hoja de apuntes. Los atributos de <perform-when> son los siguientes:
El atributo condition del elemento <conditional-subitem> proporciona un valor de serie (invariablemente este valor proviene de una variable de hoja de apuntes). Cada uno de los hijos de <subitem> debe transportar un atributo when con un valor de serie distintivo. Cuando se expande el elemento, el elemento <conditional-subitem> se sustituye por el elemento <subitem> con el valor coincidente. Si no hay ningún elemento <subitem> con un valor coincidente, se considera un error.
Por ejemplo, si la variable de hoja de apuntes llamada "v1" tiene el valor "b" cuando se expande el siguiente elemento
<item ...> <subitem label="Main step"> <perform-when condition="${v1}"> <action when="a" class="com.xyz.action1" pluginId="com.xyz" /> <action when="b" class="com.xyz.action2" pluginId="com.xyz" /> <command when="c" serialization="org.eclipse.search.ui.views.SearchView"/> </conditional-subitem> </subitem> </item>se selecciona la segunda acción y el elemento se expande en algo equivalente a
<item ...> <subitem label="Main step"> <action class="com.xyz.action2" pluginId="com.xyz" /> </subitem> </item>
Lo siguiente es un ejemplo de un archivo de contenido de hoja de apuntes simple que muestra la utilización de los subelementos de mandatos, perform-when y condicionales.
<?xml version="1.0" encoding="UTF-8" ?> <cheatsheet title="Hoja de apuntes de ejemplo"> <intro> <description>Una hoja de apuntes que muestra la utilización de los subelementos perform-when y condicionales</description> </intro> <item title="Selección de vista"> <description>Seleccionar una vista que se abrirá en los pasos siguientes</description> <command returns = "result" serialization="org.eclipse.ui.dialogs.openMessageDialog(title=Seleccionar vista,buttonLabel0=Explorador de paquetes,message=Seleccionar una vista ,buttonLabel1=Buscar vista)"/> <onCompletion> Se ha seleccionado la ${result}. </onCompletion> </item> <item title="Cerrar vistas"> <description>Cerrar la vista de búsqueda y el explorador de paquetes si están abiertos</description> </item> <item title="Abrir la vista de un elemento perform when" skip = "true"> <description>Utiliza perform when para abrir la vista seleccionada anteriormente.</description> <perform-when condition = "${result}"> <command when = "Explorador de paquetes" serialization="org.eclipse.ui.views.showView(org.eclipse.ui.views.showView.viewId=org.eclipse.jdt.ui.PackageExplorer)"/> <command when = "Vista Buscar" serialization="org.eclipse.ui.views.showView(org.eclipse.ui.views.showView.viewId=org.eclipse.search.ui.views.SearchView)"/> </perform-when> </item> <item title="Cerrar vistas"> <description>Cerrar la vista de búsqueda y el explorador de paquetes si están abiertos</description> </item> <item title="Abrir la vista de un subelemento perform when"> <description>Utiliza perform when para abrir la vista seleccionada anteriormente.</description> <subitem label="Subelemento Perform when" skip = "true"> <perform-when condition = "${result}"> <command when = "Explorador de paquetes" serialization="org.eclipse.jdt.ui.PackageExplorer"/> <command when = "Vista Buscar" serialization="org.eclipse.search.ui.views.SearchView"/> </perform-when> </subitem> </item> <item title="Cerrar vistas"> <description>Cerrar la vista de búsqueda y el explorador de paquetes si están abiertos</description> </item> <item title="Abre la vista de un subelemento condicional"> <description>Utiliza perform when para abrir la vista seleccionada anteriormente.</description> <conditional-subitem condition="${result}"> <subitem when="Explorador de paquetes" label="Abrir explorador de paquetes."> <command serialization = "org.eclipse.jdt.ui.PackageExplorer"/> </subitem> <subitem when="Vista Buscar" label="Abrir vista Buscar"> <command serialization = "org.eclipse.search.ui.views.SearchView"/> </subitem> </conditional-subitem> </item> </cheatsheet>
Copyright (c) 2004, 2006 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