Versão 3.2
Este documento descreve a estrutura do ficheiro de conteúdo de folha de apontamentos como uma série de fragmentos DTD (esquema XML legível pela máquina).
cheatsheet
<!ELEMENT cheatsheet (intro, item+)> <!ATTLIST cheatsheet title CDATA #REQUIRED >
O elemento <cheatsheet> define o corpo do ficheiro de conteúdo de 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 apresentada. 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> contém a descrição de uma folha de apontamentos ou de um artigo de folha de apontamentos. A descrição é composta por texto intercalado com identificadores de formato simples. A folha de apontamentos formata e dispõe automaticamente o texto, para que este seja correctamente mostrado na UI. No texto, os identificadores <b>...</b> iniciais e finais fazem com que o texto englobado fique a negrito e o elemento <br/> pode ser utilizado para forçar uma quebra de linha. Estes são os únicos identificadores suportados actualmente (no entanto, poderão ser adicionados outros no futuro). Determinados caracteres do texto possuem um significado especial para interpretadores de XML; em particular, em vez de escrever "<", ">", "&", """ e """ (aspas), escreva "<", ">", "&", "'" e""" respectivamente. Os espaços em branco (espaços e quebras de linha) são considerados separadores de palavras; os espaços adjacentes e as quebras de linha são considerados uma única unidade e são visualizados como um único espaço ou quebra de linha. Os espaços em branco imediatamente após os identificadores <description> e <br/> são ignorados, tal como os espaços em branco imediatamente antes do identificador </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 um passo do nível mais elevado de uma folha de apontamentos. Um <item> pode conter elementos <subitem>. Os atributos de <item> são os seguintes:
O ponto de extensão org.eclipse.ui.cheatsheets.cheatSheetItemExtension permite apresentar controlos personalizados adicionais do artigo na UI. As contribuições deste ponto de extensão declaram os nomes de atributos adicionais com valor de cadeia, que podem aparecer em elementos <item>.
Os artigos simples possuem uma descrição e uma acção opcional ou comando. Na apresentação normal, os títulos de artigos de folha de apontamentos são mostrados ao utilizador a maior parte do tempo. A descrição de um artigo só é mostrada enquanto o passo está a ser executado. A presença de um elemento <action>, <command> ou <perform-when>)está associada a um botão que o utilizador pode premir para executar a acção do passo ou comando. Caso não haja qualquer acção ou comando, o passo deve ser executado manualmente pelo utilizador, para de seguida indicar explicitamente que o concluiu com êxito.
Os passos compostos estão divididos em sub-passos, tal como está especificado pelos sub-elementos <subitem>. Ao contrário dos artigos, que o utilizador deve executar segundo uma sequência rígida, os sub-artigos de um determinado artigo podem ser executados segundo qualquer ordem. Todos os sub-artigos dentro de um artigo têm de ser tentados (ou ignorados) antes de avançar para o artigo seguinte. (O que significa que as acções que têm de ser executadas segundo uma sequência obrigatória não podem ser representadas em sub-artigos.)
Um sub-elemento <conditional-subitem> permite que um passo adeqúe a apresentação de um sub-passo, com base em variáveis de folha de apontamentos cujos valores são adquiridos em passos anteriores. Um sub-elemento <repeated-subitem> permite que um passo inclua um conjunto de sub-passos semelhantes. Mais uma vez, o conjunto exacto de sub-passos pode basear-se nas variáveis de folha de apontamentos cujos valores são adquiridos em passos anteriores.
subitem
<!ELEMENT subitem ( [action|command|perform-when] )> <!ATTLIST subitem label CDATA #REQUIRED skip ("true" | "false") "false" when CDATA #IMPLIED >
Cada elemento <subitem> descreve um sub-passo numa folha de apontamentos. Um <subitem> possui uma etiqueta de texto simples, mas não possui uma descrição extensa, nem outros sub-artigos. Os atributos de <subitem> são os seguintes:
Os sub-artigos possuem uma acção opcional ou comando. A presença de um elemento <action>, <command> ou <perform-when> está associada a um botão que o utilizador pode premir para executar a acção do sub-passo ou comando. Caso não haja qualquer acção ou comando, o sub-passo deve ser executado manualmente pelo utilizador, para de seguida indicar explicitamente que o concluiu com êxito.
Ao contrário dos artigos, que devem ser executados segundo uma sequência rígida, os sub-artigos de um determinado artigo podem ser executados segundo qualquer ordem. Todos os sub-artigos dentro de um artigo têm de ser concluídos ou ignorados antes de avançar para o artigo seguinte. (O que significa que as acções que têm de ser executadas segundo uma sequência obrigatória não devem ser representadas em sub-artigos.)
conditional-subitem
<!ELEMENT conditional-subitem (subitem+)> <!ATTLIST conditional-subitem condition CDATA #REQUIRED >
Cada elemento <conditional-subitem> descreve um único sub-passo, cujo formato pode diferir, com base num condição conhecida na altura em que o artigo é expandido. Os atributos de <conditional-subitem> são os seguintes:
O atributo condition no elemento <conditional-subitem> faculta um valor de cadeia (invariavelmente, este valor provém de uma variável de folha de apontamentos). Cada um dos descendentes de <subitem> deve transportar um atributo when com um valor de cadeia distinto. Quando o artigo é expandido, o elemento <conditional-subitem> é substituído pelo elemento <subitem> com o valor correspondente. É considerado um erro se não existir qualquer elemento <subitem> com um valor correspondente.
Por exemplo, caso a variável de folha de apontamentos designada "v1" possuir o valor "b" quando o seguinte artigo for expandido,
<item ...> <conditional-subitem condition="${v1}"> <subitem when="a" label="Step for A." /> <subitem when="b" label="Step for B." /> </conditional-subitem> </item>então o segundo sub-artigo é seleccionado e o artigo expande 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-artigo que expande para 0, 1 ou mais sub-passos semelhantes. Os atributos de <repeated-subitem> são os seguintes:
O atributo values faculta uma lista de cadeias separadas por vírgula; o descendente de <subitem> serve de modelo. Quando o artigo é 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, caso a variável de folha de apontamentos designada "v1" possuir o valor "1,b,three" quando o seguinte artigo 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>então o artigo expande 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 acção numa folha de apontamentos. Os atributos de <action> são os seguintes:
org.eclipse.jface.action.IAction
.
Caso esta acção também implemente org.eclipse.ui.cheatsheets.ICheatSheetAction
, será invocada por intermédio do método run(String[],ICheatSheetManager) e ser-lhe-á transmitido o gestor de folhas de anotações e os parâmetros de acção. O atributo pluginId tem de existir sempre que este atributo existir.
Recomenda-se vivamente que as acções que se pretendam invocar em folhas de
anotações comuniquem resultados de êxito/falha, caso a execução da acção
falhe (talvez devido ao cancelamento da acção, por parte do utilizador, na
respectiva caixa de diálogo). (Consulte
org.eclipse.jface.action.Action.notifyResult(boolean) para obter detalhas.)org.eclipse.ui.cheatsheets.ICheatSheetAction
, os valores de cadeia destes atributos são transmitidos à acção quando esta é invocada. O utilizador pode transmitir até 9 parâmetros a uma acção de folha de apontamentos (param1,
param2, etc.). Os parâmetros facultados têm de começar com o parâmetro 1 e ser contíguos; ou seja não é permitido especificar param2 sem que param1 também exista. Caso a cadeia de atributo possua o formato "${var}",
é 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 da folha de apontamentos, no início da execução do elemento contentor <item> (ou da cadeia vazia, caso a variável esteja desassociada nessa altura).command
<!ELEMENT command EMPTY> <!ATTLIST command serialization CDATA #REQUIRED returns CDATA #IMPLIED confirm ("true" | "false") "false" when CDATA #IMPLIED >
Cada elemento <command> descreve um comando numa folha de apontamentos. Os atributos <command> são os seguintes:
Em seguida é apresentado um exemplo de um artigo com um comando que abre uma caixa de diálogo e que armazena os resultados numa variável de folha de apontamentos "result".
<item title="View Selection"> <description>Select a view which will be opened in the next step.</description> <command returns = "result" serialization="org.eclipse.ui.dialogs.openMessageDialog(title=Select View,buttonLabel0=Package Explorer,message=Select a view ,buttonLabel1=Search View)"/> <onCompletion> Selected the ${result}. </onCompletion> </item>
onCompletion
<!ELEMENT onCompletion EMPTY> <!ATTLIST onCompletion >
O elemento <onCompletion> contém texto que é apresentado após a conclusão de um artigo. Esta apresentação é útil no último passo da folha de apontamentos, uma vez que informa que a tarefa está totalmente concluída. A descrição é composta por texto intercalado com identificadores de formato simples que respeitam as mesmas regras de um elemento <description>. Os elementos <onCompletion> podem também conter referências a variáveis de folhas de apontamentos do formato "${var}", que serão expandidas através da utilização do valor real das variáveis de folhas de apontamentos var aquando da conclusão deste passo.
perform-when
<!ELEMENT perform-when ((action|command)+)> <!ATTLIST perform-when condition CDATA #REQUIRED >
Cada elemento <perform-when> descreve uma acção numa folha de apontamentos. Os atributos de <perform-when> são os seguintes:
O atributo condition no elemento <conditional-subitem> faculta um valor de cadeia (invariavelmente, este valor provém de uma variável de folha de apontamentos). Cada um dos descendentes de <subitem> deve transportar um atributo when com um valor de cadeia distinto. Quando o artigo é expandido, o elemento <conditional-subitem> é substituído pelo elemento <subitem> com o valor correspondente. É considerado um erro se não existir qualquer elemento <subitem> com um valor correspondente.
Por exemplo, caso a variável de folha de apontamentos designada "v1" possuir o valor "b" quando o seguinte artigo 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>então a segunda acção é seleccionada e o artigo expande para algo equivalente a
<item ...> <subitem label="Main step"> <action class="com.xyz.action2" pluginId="com.xyz" /> </subitem> </item>
De seguida é apresentado um exemplo de um ficheiro de conteúdo de folha de apontamentos muito simples que demonstra a utilização de sub-artigos de comandos, de altura de execução e condicionais.
<?xml version="1.0" encoding="UTF-8"?> <cheatsheet title="Sample Cheat Sheet"> <intro> <description>A cheat sheet which demonstrates the use of perform-when and conditional subitems</description> </intro> <item title="View Selection"> <description>Select a view which will be opened in the following steps.</description> <command returns = "result" serialization="org.eclipse.ui.dialogs.openMessageDialog(title=Select View,buttonLabel0=Package Explorer,message=Select a view ,buttonLabel1=Search View)"/> <onCompletion> Selected the ${result}. </onCompletion> </item> <item title="Close Views"> <description>Close the search view and package explorer if open</description> </item> <item title="Open the view from a perform when item" skip = "true"> <description>Uses perform when to open the view seleted previously.</description> <perform-when condition = "${result}"> <command when = "Package Explorer" serialization="org.eclipse.ui.views.showView(org.eclipse.ui.views.showView.viewId=org.eclipse.jdt.ui.PackageExplorer)"/> <command when = "Search View" serialization="org.eclipse.ui.views.showView(org.eclipse.ui.views.showView.viewId=org.eclipse.search.ui.views.SearchView)"/> </perform-when> </item> <item title="Close Views"> <description>Close the search view and package explorer if open</description> </item> <item title="Open the view from a perform when subitem"> <description>Uses perform when to open the view seleted previously.</description> <subitem label="Perform when subitem" skip = "true"> <perform-when condition = "${result}"> <command when = "Package Explorer" serialization="org.eclipse.jdt.ui.PackageExplorer"/> <command when = "Search View" serialization="org.eclipse.search.ui.views.SearchView"/> </perform-when> </subitem> </item> <item title="Close Views"> <description>Close the search view and package explorer if open</description> </item> <item title="Open the view from a conditional subitem"> <description>Uses perform when to open the view seleted previously.</description> <conditional-subitem condition="${result}"> <subitem when="Package Explorer" label="Open package explorer."> <command serialization = "org.eclipse.jdt.ui.PackageExplorer"/> </subitem> <subitem when="Search View" label="Open Search View"> <command serialization = "org.eclipse.search.ui.views.SearchView"/> </subitem> </conditional-subitem> </item> </cheatsheet>
Copyright (c) 2004, 2006 IBM Corporation e outros.
Todos os direitos reservados. Este programa e os materiais que o acompanham estão disponíveis sob os termos da Eclipse Public License v1.0, que acompanha esta distribuição e estão disponíveis em http://www.eclipse.org/legal/epl-v10.html