Versión 3.0
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|perform-when] | (subitem|repeated-subitem|conditional-subitem)*))> <!ATTLIST item title CDATA #REQUIRED 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. El elemento <item> puede ser simple o compuesto. 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 simples tienen una descripción y una acción opcional. 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> (o <perform-when>) está asociada generalmente con un botón que el usuario puede pulsar para realizar la acción del paso. Si no hay ninguna acción, el usuario debe llevar a cabo el paso manualmente y, a continuación, indicar explícitamente que lo ha realizado satisfactoriamente.
Los pasos compuestos se dividen 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|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 tienen una acción opcional. La presencia de un elemento <action> (o <perform-when>) está asociada generalmente con un botón que el usuario puede pulsar para realizar la acción del subpaso. Si no hay ninguna acción, 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 intentarse (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).perform-when
<!ELEMENT perform-when (action+)> <!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" /> </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>
A continuación figura un ejemplo de un archivo de contenido de hoja de apuntes sencilla:
<?xml version="1.0" encoding="UTF-8" ?> <cheatsheet title="Ejemplo"> <intro> <description>Hoja de apuntes de ejemplo con dos pasos.</description> </intro> <item title="Paso 1"> <description>Este es un paso con una acción.</description> <action class="com.xyz.myaction" pluginId="com.xyz"/> </item> <item title="Paso 2"> <description>Este es un paso totalmente manual.</description> </item> </cheatsheet>
Copyright (c) 2004 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