Versão 3.2
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 title 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 tags 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, tags <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 tags de formato suportadas nesse momento (contudo, outras podem ser incluídas no futuro). Determinados caracteres no texto têm significados especiais para analisadores XML; em particular, 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 tags <description> e <br/> é ignorado, assim como imediatamente antes da tag </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> descreve uma etapa de nível superior em uma folha de apontamentos. Um <item> pode conter elementos de <subitem>. 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 ou comando 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>, <command> ou <perform-when>) está associada a um botão que o usuário pode pressionar para executar a ação ou o comando da etapa. Se nenhuma ação ou comando 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|command|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:
Subitens podem ter uma ação ou um comando opcional. A presença de um elemento <action>, <command> ou <perform-when> geralmente está associada a um botão que o usuário pode pressionar para executar a ação ou o comando da subetapa. Se nenhuma ação ou comando 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 subitens de um item devem ser concluídos (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 modelo. 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).comando
<!ELEMENT command EMPTY> <!ATTLIST command serialization CDATA #REQUIRED returns CDATA #IMPLIED confirm ("true" | "false") "false" when CDATA #IMPLIED >
Cada elemento <command> descreve um comando em uma folha de dicas. Os atributos <command> são os seguintes:
A seguir, há um exemplo de um item com um comando que abre uma caixa de diálogo e armazena o resultado em uma variável da folha de dicas "result".
<item title="Visualizar Seleção"> <description>Selecione uma visualização que será aberta na próxima etapa.</description> <command returns = "result" serialization="org.eclipse.ui.dialogs.openMessageDialog(title=Selecionar Visualização,buttonLabel0=Explorador de Pacotes,message=Selecione uma visualização,buttonLabel1=Visualização de Procura)"/> <onCompletion> Selecionado o ${result}. </onCompletion> </item>
onCompletion
<!ELEMENT onCompletion EMPTY> <!ATTLIST onCompletion >
O elemento <onCompletion> contém texto que será exibido quando um item for exibido. Isso é especialmente útil na etapa final da folha de dicas para confirmar a conclusão da tarefa inteira. A descrição consiste no texto intercalado com tags de formato simples, seguindo as mesmas regras para um elemento <description>. Os elementos <onCompletion> também podem conter referências para variáveis da folha de dicas do formulário "${var}", que serão expandidos utilizando o valor real da variável da folha de dicas var no momento em que essa etapa foi concluída.
perform-when
<!ELEMENT perform-when ((action|command)+)> <!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" /> <command when="c" serialization="org.eclipse.search.ui.views.SearchView"/> </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>
A seguir, há um exemplo de um arquivo simples de conteúdo de folha de dicas, que demonstra o uso de comandos, perform-when e subitens condicionais.
<?xml version="1.0" encoding="UTF-8"?> <cheatsheet title="Amostra de Folha de Dicas"> <intro> <description>Uma folha de dicas que demonstra o uso de perform-when e subitens condicionais</description> </intro> <item title="Visualizar Seleção"> <description>Selecione uma visualização que será aberta nas próximas etapas.</description> <command returns = "result" serialization="org.eclipse.ui.dialogs.openMessageDialog(title=Selecionar Visualização,buttonLabel0=Explorador de Pacotes,message=Selecione uma visualização,buttonLabel1=Visualização de Procura)"/> <onCompletion> Selecionado o ${result}. </onCompletion> </item> <item title="Fechar Visualizações"> <description>Feche a visualização de procura e um explorador de pacotes se aberto</description> </item> <item title="Abra a visualização de um item perform when" skip = "true"> <description>Utiliza um item perform when para abrir a visualização selecionada anteriormente.</description> <perform-when condition = "${result}"> <command when = "Explorador de Pacotes" serialization="org.eclipse.ui.views.showView(org.eclipse.ui.views.showView.viewId=org.eclipse.jdt.ui.PackageExplorer)"/> <command when = "Visualização de Procura" serialization="org.eclipse.ui.views.showView(org.eclipse.ui.views.showView.viewId=org.eclipse.search.ui.views.SearchView)"/> </perform-when> </item> <item title="Fechar Visualizações"> <description>Feche a visualização de procura e um explorador de pacotes se aberto</description> </item> <item title="Abra a visualização de um subitem perform when"> <description>Utiliza um item perform when para abrir a visualização selecionada anteriormente.</description> <subitem label="Subitem perform when" skip = "true"> <perform-when condition = "${result}"> <command when = "Explorador de Pacotes" serialization="org.eclipse.jdt.ui.PackageExplorer"/> <command when = "Visualização de Procura" serialization="org.eclipse.search.ui.views.SearchView"/> </perform-when> </subitem> </item> <item title="Fechar Visualizações"> <description>Feche a visualização de procura e um explorador de pacotes se aberto</description> </item> <item title="Abra a visualização de um subitem condicional"> <description>Utiliza um item perform when para abrir a visualização selecionada anteriormente.</description> <conditional-subitem condition="${result}"> <subitem when="Explorador de Pacotes" label="Abrir explorador de pacotes."> <serialização do comando = "org.eclipse.jdt.ui.PackageExplorer"/> </subitem> <subitem when="Visualização de Procura" label="Abrir Visualização de Procura"> <serialização do comando = "org.eclipse.search.ui.views.SearchView"/> </subitem> </conditional-subitem> </item> </cheatsheet>
Direitos Autorais (c) 2004, 2006 IBM Corporation e outros.
Todos os direitos reservados.
Este programa e os materiais fornecidos com ele são
disponibilizados sob os termos da Licença Pública do Eclipse v1.0 que acompanha
esta distribuição e está disponível em
http://www.eclipse.org/legal/epl-v10.html