Versão 3.0
Este documento descreve a estrutura do arquivo de conteúdo da folha de apontamentos como uma série de fragmentos DTD (esquema XML legível da máquina).
cheatsheet
<folha de apontamentos do !ELEMENT (intro, item+)> <folha de apontamentos do !ATTLIST título CDATA #REQUIRED >
O elemento <cheatsheet> define o corpo de um arquivo de conteúdo da folha de apontamentos. Os atributos de <cheatsheet> são os seguintes:
intro
<!ELEMENT intro (description)> <!ATTLIST intro contextId CDATA #IMPLIED href CDATA #IMPLIED >
O elemento <intro> é utilizado para descrever a introdução da folha de apontamentos a ser exibida. O sub-elemento <description> contém o corpo da introdução. Os atributos de <intro> são os seguintes:
description
<!ELEMENT description EMPTY> <!ATTLIST description >
O elemento <description> mantém a descrição de uma folha de apontamentos ou de um item da folha de apontamentos. A descrição consiste no texto intercalado com marcações de formato simples. A folha de apontamentos formata e define o layout automaticamente do texto para que seja exibido corretamente na UI. Dentro do texto, marcações <b>...</b> compensadas fazem com que o texto incluído seja processado em fonte negrito e o elemento <br/> pode ser utilizado para forçar uma quebra de linha. Essas são as únicas marcações de formato suportadas nesse momento (contudo, outras podem ser incluídas no futuro). Determinados caracteres no texto possuem significância especial para analisadores XML; em particular, para gravar "<", ">", "&", "'" e """ (aspas) em vez de gravar "<", ">", "&", "'" e """ respectivamente. Espaço em branco (espaços e quebras de linha) é tratado como um separador de palavras; espaços adjacentes e quebras de linha são tratados como unidade individual e processados como um espaço individual ou uma quebra de linha. Espaço em branco imediatamente após as marcações <description> e <br/> é ignorado, assim como imediatamente antes da marcação </description>.
item
<!ELEMENT item (description ([action|perform-when] | (subitem|repeated-subitem|conditional-subitem)*))> <!ATTLIST item título CDATA #REQUIRED skip ("true" | "false") "false" contextId CDATA #IMPLIED href CDATA #IMPLIED >
Cada elemento <item> descreve uma etapa de nível superior em uma folha de apontamentos. O <item> é simples ou composto. Os atributos <item> são os seguintes:
O org.eclipse.ui.cheatsheets.cheatSheetItemExtension permite controles personalizados adicionais para o item a ser exibido na UI. As contribuições para este ponto de extensão declaram os nomes dos atributos de valor de cadeia adicionais que podem aparecer nos elementos <item>.
Itens simples possuem uma descrição e uma ação opcional. Na apresentação típica, os títulos dos itens da folha de apontamentos são mostrados para o usuário na maior parte do tempo. A descrição de um item só é mostrada enquanto a etapa está em processo de ser executada. A presença de um elemento <action> (ou <perform-when>) normalmente está associada a um botão que o usuário pode pressionar para executar a ação da etapa. Se nenhuma ação estiver presente, a etapa será a única que o usuário deverá executar manualmente e depois indicar abertamente que a etapa foi concluída com êxito.
Etapas compostas são divididas em subetapas, conforme especificado pelos subelementos <subitem>. Ao contrário dos itens, que o usuário deve seguir na seqüência estrita, os sub-itens de um determinado item podem ser executados em qualquer ordem. Todos os sub-itens em um item devem ser tentados (ou ignorados) antes do processamento do próximo item. (O que significa que as ações que devem ser executadas em uma seqüência obrigatória não podem ser representadas como sub-itens.)
Um subelemento <conditional-subitem> permite que uma etapa adapte a apresentação de uma subetapa com base nas variáveis de folha de apontamentos cujos valores são obtidos em etapas anteriores. Um subelemento <repeated-subitem> permite que uma etapa inclua um conjunto de subetapas semelhantes. Novamente, o conjunto exato de subetapas pode basear-se nas variáveis de folha de apontamentos cujo valor seja obtido em etapas anteriores.
subitem
<!ELEMENT subitem ( [action|perform-when] )> <!ATTLIST subitem label CDATA #REQUIRED skip ("true" | "false") "false" when CDATA #IMPLIED >
Cada elemento <subitem> descreve uma subetapa em uma folha de apontamentos. Um <subitem> transporta uma etiqueta de texto simples, mas não tem uma descrição longa nem sub-itens adicionais. Os atributos <subitem> são os seguintes:
Sub-itens possuem uma ação opcional. A presença de um elemento <action> (ou <perform-when>) normalmente está associada a um botão que o usuário pode pressionar para executar a ação da subetapa. Se nenhuma ação estiver presente, a subetapa será a única que o usuário deverá executar manualmente e depois indicar abertamente que a etapa foi concluída com êxito.
Diferente dos itens, que devem ser seguidos em uma seqüência estrita, os sub-itens de um determinado item podem ser executados em qualquer outra ordem. Todos os sub-itens em um item devem ser tentados (ou ignorados) antes do processamento do próximo item. (Isso significa que ações que devem ser executadas em uma seqüência obrigatória não devem ser representadas como sub-items.)
conditional-subitem
<!ELEMENT conditional-subitem (subitem+)> <!ATTLIST conditional-subitem condition CDATA #REQUIRED >
Cada elemento <conditional-subitem> descreve uma única subetapa cujo formato pode diferir, com base em uma condição conhecida no momento que o item é expandido. Os atributos <conditional-subitem> são os seguintes:
O atributo condition no elemento <conditional-subitem> fornece um valor de cadeia (esse valor provém invariavelmente de uma variável de folha de apontamentos). Cada filho do elemento <subitem> deve conter um atributo when com um valor de cadeia distinto. Quando o item é expandido, o elemento <conditional-subitem> é substituído pelo elemento <subitem> com o valor de correspondência. Isso será considerado um erro, se não houver o elemento <subitem> com um valor de correspondência.
Por exemplo, se a variável de folha de apontamentos denominada "v1" possuir o valor "b" quando o seguinte item for expandido
<item ...> <conditional-subitem condition="${v1}"> <subitem when="a" label="Step for A." /> <subitem when="b" label="Step for B." /> </conditional-subitem> </item>o segundo sub-item será selecionado e o item será expandido para 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> descreve um sub-item que é expandido em 0, 1 ou mais subetapas semelhantes. Os atributos <repeated-subitem> são os seguintes:
O atributo values fornece uma lista de cadeias separadas por vírgula; o <subitem> filho fornece o gabarito. Quando o item é expandido, o elemento <repeated-subitem> é substituído por cópias do elemento <subitem> com ocorrências da variável "this" substituídas pelo valor de cadeia correspondente.
Por exemplo, se a variável de folha de apontamentos denominada "v1" possuir o valor "1,b,three" quando o seguinte item for expandido
<item ...> <repeated-subitem values="${v1}"> <subitem label="Step ${this}."> <action class="com.xyz.myaction" pluginId="com.xyz" param1="${this}"/> </subitem> </repeated-subitem> </item>o item será expandido para 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> descreve uma ação em uma folha de apontamentos. Os atributos <action> são os seguintes:
org.eclipse.jface.action.IAction
. Se essa ação também implementar
org.eclipse.ui.cheatsheets.ICheatSheetAction
, ela será chamada por meio
do método run(String[],ICheatSheetManager) e serão transmitidos os parâmetros de ação e
gerenciador da folha de apontamentos. O atributo pluginId deve estar presente sempre
que esse atributo também estiver. É expressamente recomendável que as ações
planejadas para serem chamadas das folhas de apontamento relatem o resultado de
sucesso/falha, se a execução da ação tiver possibilidade de falhar (talvez por que o
usuário cancela a ação em seu diálogo). (Consulte
org.eclipse.jface.action.Action.notifyResult(boolean) para obter detalhes.)org.eclipse.ui.cheatsheets.ICheatSheetAction
, os valores de cadeia
desses atributos são transmitidos à ação quanto ela é chamada. É possível
transmitir até 9 parâmetros para uma ação de folha de apontamentos (param1,
param2, etc.). Os parâmetros fornecidos devem começar com o parâmetro 1 e
serem contíguos; ou seja, é inválido especificar param2 sem que param1
também esteja presente. Se a cadeia do atributo tiver o formato
"${var}", ela será considerada uma referência a uma variável de
folha de apontamentos var e o valor da condição será o valor da variável para
a folha de apontamentos no início da execução que contém o elemento <item> (ou
a cadeia vazia, se a variável estiver desvinculada nesse momento).perform-when
<!ELEMENT perform-when (action+)> <!ATTLIST perform-when condition CDATA #REQUIRED >
Cada elemento <perform-when> descreve uma ação em uma folha de apontamentos. Os atributos <perform-when> são os seguintes:
O atributo condition no elemento <conditional-subitem> fornece um valor de cadeia (esse valor provém invariavelmente de uma variável de folha de apontamentos). Cada filho do elemento <subitem> deve conter um atributo when com um valor de cadeia distinto. Quando o item é expandido, o elemento <conditional-subitem> é substituído pelo elemento <subitem> com o valor de correspondência. Isso será considerado um erro, se não houver o elemento <subitem> com um valor de correspondência.
Por exemplo, se a variável de folha de apontamentos denominada "v1" possuir o valor "b" quando o seguinte item for expandido
<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>a segunda ação será selecionada e o item será expandido para algo equivalente a:
<item ...> <subitem label="Main step"> <action class="com.xyz.action2" pluginId="com.xyz" /> </subitem> </item>
Segue um exemplo de arquivo simples de conteúdo de folha de apontamentos:
<?xml version="1.0" encoding="UTF-8"?> <cheatsheet title="Example"> <intro> <description>Exemplo de folha de apontamentos com duas etapas.</description> </intro> <item title="Etapa 1"> <description>Esta é uma etapa com uma ação.</description> <action class="com.xyz.myaction" pluginId="com.xyz"/> </item> <item title="Etapa 2"> <description>Esta é uma etapa totalmente manual.</description> </item> </cheatsheet>
Direitos Autorais (c) 2004 IBM Corporation e outros.
Todos os direitos reservados.
Este programa e os materiais que o acompanham são disponibilizados
sob os termos da Eclipse Public License v1.0 que acompanha esta
distribuição e estão disponíveis no endereço http://www.eclipse.org/legal/epl-v10.html