As folhas de apontamentos podem ajudar a orientar o utilizador ao longo de
várias tarefas complexas no intuito de atingir uma finalidade global. Por exemplo, pode utilizar-se uma folha de apontamentos para ajudar a orientar o utilizador pelos passos necessários à criação, compilação e execução de um simples programa Java.
As folhas de apontamentos são lançadas a partir da opção de menu
Ajuda > Folhas de Apontamentos...
. As folhas de anotações também podem ser lançadas a partir de uma página de introdução.
As folhas de anotações são definidas por meio do ponto de extensão org.eclipse.ui.cheatsheets.cheatSheetContent. O conteúdo da folha de apontamentos propriamente dito está definido num ficheiro separado para ser mais fácil a respectiva tradução noutros idiomas.
É muito simples contribuir com uma folha de apontamentos. Vejamos uma folha de apontamentos contributo das JDT para construir uma simples aplicação Java.
<extension point="org.eclipse.ui.cheatsheets.cheatSheetContent"> <cheatsheet name="%cheatsheet.helloworld.name" contentFile="$nl$/cheatsheets/HelloWorld.xml" id="org.eclipse.jdt.helloworld"> <description>%cheatsheet.helloworld.desc</description> </cheatsheet> ...À semelhança de outros contributos da área de trabalho, podem ser especificados nome, descrição e ID para a folha de apontamentos. O nome e a descrição são apresentados quando o utilizador acede à lista
O verdadeiro trabalho das folhas de anotações realiza-se no ficheiro de conteúdo. O ficheiro de conteúdo é um ficheiro XML cujos nome e localização são especificados no atributo contentFile. O caminho para o ficheiro é relativo ao directório de plug-ins. (Repare que a utilização da variável $nl$ no nome de directório, que significa que o ficheiro será localizado num directório específico do idioma nacional do ambiente destino.)
O próprio formato do ficheiro inclui informações de descrição geral sobre a folha de apontamentos, seguidas de uma descrição de cada passo (denominado artigo) que o utilizador realizará. Em termos mais simples, um artigo é somente uma descrição detalhada do passo que o utilizador deve dar. Todavia, um artigo também pode especificar uma acção que pode ser executada para dar o passo em nome do utilizador. vejamos a primeira parte do ficheiro de conteúdo (HelloWorld.xml) da folha de apontamentos Java.
<?xml version="1.0" encoding="UTF-8" ?> <cheatsheet title="Simple Java Application"> <intro href="/org.eclipse.ui.cheatsheets.doc/tasks/tcheatst.htm"> <description> Bem-vindo(a) ao guia de iniciação Java Hello World. Este destina-se a ajudar a construir e a testar a famosa aplicação "hello world". O utilizador irá criar um projecto Java e uma classe Java que irão imprimir "hello world" na consola quando executado. Vamos começar! </description> </intro> <item href="/org.eclipse.platform.doc.user/concepts/concepts-4.htm" title="Abrir a Perspectiva Java"> <action pluginId="org.eclipse.ui.cheatsheets" class="org.eclipse.ui.internal.cheatsheets.actions.OpenPerspective" param1="org.eclipse.jdt.ui.JavaPerspective"/> <description> Seleccione Janela->Abrir Perspectiva->Java na barra de menus no topo da área de trabalho. Este passo altera a perspectiva para configurar a área de trabalho do Eclipse para desenvolvimento Java. Pode fazer clique no botão "Faça clique para Executar" para que a perspectiva "Java" se abra automaticamente. </description> </item> ...
As informações de título e introdução são apresentadas no topo da folha de apontamentos. De seguida é apresentada a descrição dos artigos. O primeiro artigo para esta folha de apontamentos descreve como abrir a perspectiva Java. Melhor ainda, o atributo action pode ser usado para executar a acção em nome do utilizador. A classe deve implementar IAction. Isto é conveniente porque permite reutilizar as classes de acção escritas para contributos de menus ou barras de ferramentas.
A classe para a acção pode implementar opcionalmente ICheatSheetAction se a acção utilizar parâmetros ou precisar de saber da folha de apontamentos e respectivo estado. Neste caso, é transmitida à acção uma matriz de parâmetros e uma referência ao ICheatSheetManager para este poder pedir mais informações sobre a folha de apontamentos. Os parâmetros necessários podem ser transmitidos ao método run da acção com os atributos paramN.
Recomenda-se vivamente que as acções invocadas a partir de folhas de anotações reportem um resultado de sucesso/falha caso a execução da acção possa falhar. (Por exemplo, o utilizador poderia cancelar a acção a partir da respectiva caixa de diálogo.) Consulte IAction.notifyResult(boolean) para mais detalhes.
Os artigos não têm que definir acções. Se o artigo tiver de ser executado manualmente pelo utilizador não será preciso especificar acção alguma. De seguida é apresentado o terceiro passo da folha de apontamentos Java, ao qual indica meramente ao utilizador como programar a aplicação simples. Quando não é especificada acção alguma, a descrição do artigo deve instruir o utilizador a premir o botão apropriado depois de a tarefa estar concluída.
<item href="/org.eclipse.jdt.doc.user/tasks/tasks-54.htm" title="Adicionar uma linha System.out.println ao método principal"> <description> Agora que temos a classe HelloWorld, No método "public static void main", adicionamos a seguinte instrução: System.out.println("Hello world!"); e guardamos as alterações. Prima o botão "clique quando terminado" abaixo quando concluir. </description> </item>Os atributos adicionais controlam se o artigo pode ou não ser ignorado completamente e que documento deve ser iniciado se o utilizador pedir ajuda durante o passo. Consulte a documentação do ponto de extensão org.eclipse.ui.cheatsheets.cheatSheetContent para ver uma descrição de todos os atributos que podem ser definidos dentro de uma folha de apontamentos.
Podem ser definidos sub-artigos para organizar melhor a apresentação de um artigo. Ao invés dos artigos, os sub-artigos não têm que ser visitados em determinada ordem. Os sub-artigos também podem definir acções que realizam automaticamente a sub-tarefa pelo utilizador. As acções de sub-artigos são descritas da mesma forma que acções de artigos.
Podem ser usadas expressões condicionais para definir elementos de folha de apontamentos cujo conteúdo e comportamento dependa da veracidade de certa condição (true). As condições estão descritas no elemento condition de um sub-artigo mediante valores de cadeia de caracteres arbitrários que correspondem ao atributo when para cada escolha. As condições referenciam normalmente variáveis de folha de apontamentos no formato ${var}, em que var remete para o nome da variável de folha de apontamentos. Uns exemplos simples ajudam a demonstrar o funcionamento das expressões condicionais.
Podem ser usados sub-artigos condicionais para escolher um sub-artigo numa lista de sub-artigos possíveis. Somente o primeiro sub-artigo cujo atributo when corresponda ao atributo de condição é incluído na folha de apontamentos. Por exemplo:
<item ...> <conditional-subitem condition="${v1}"> <subitem when="a" label="Passo para A." /> <subitem when="b" label="Passo para B." /> </conditional-subitem> </item>Este artigo especifica dois sub-artigos possíveis que dependem do valor da variável v1. Se o valor da variável for a, será incluído o primeiro sub-artigo. Se o valor da variável for b, será incluído o segundo sub-artigo. Se a variável não for nenhum dos valores, será considerada um erro.
As acções condicionais são semelhantes aos sub-artigos condicionais. O elemento perform-when especifica uma condição para executar uma acção dentre uma lista de acções possíveis. A condição está descrita da mesma forma, mediante cadeia de caracteres arbitrária que costuma referenciar uma variável. a acção cujo atributo when corresponde à condição é aquela que será realizada. Por exemplo:
<item ...> <perform-when condition="${v1}"> <action when="a" class="com.example.actionA" pluginId-"com.example" /> <action when="b" class="com.example.actionB" pluginId-"com.example" /> </perform-when> </item>A acção a realizar é escolhida com base no valor da variável v1. Se a variável não for a nem b, será considerada um erro.
Os sub-artigos repetidos descrevem um sub-artigo que se pode expandir em 0, 1 ou mais sub-passos semelhantes. os sub-passos são individualizados através da variável especial ${this}. Esta variável será substituída pelos valores especificados no atributo values. O atributo values é uma cadeia de valores separados por vírgulas. Poderá ser usada uma variável que se expande numa lista de valores no atributo values. Por exemplo:
<item ...> <repeated-subitem values="${v1}"> <subitem label="Passo ${this}" /> </repeated-subitem> </item>Se o valor da variável for 1,b,três, aparecem três sub-artigos na folha de apontamentos, cada qual com uma etiqueta única ("Passo 1", "Passo b", Passo três"). A variável pode ser usada na etiqueta ou no valor do parâmetro de acção. Também pode ser acedida a partir do ICheatSheetManager enquanto a acção estiver a executar.
Em alguns casos, poderá ser útil alterar outras partes da UI se estiver activa uma folha de apontamentos. Por exemplo, poderá ter um editor que mostre anotações especiais se houver uma folha de apontamentos a orientar o utilizador na edição de uma tarefa. Neste caso, pode ser especificado um ouvinte como atributo da folha de apontamentos. O atributo ouvinte deve ser o nome totalmente qualificado de uma classe Java que constitua uma subclasse de CheatSheetListener. Os ouvintes recebem notificações junto com um ICheatSheetEvent quando houver uma alteração no ciclo de vida da folha de apontamentos como, por exemplo, abrir, fechar ou concluir.
A extensão org.eclipse.ui.cheatsheets.cheatSheetItemExtension pode ser usada para contribuir com atributos arbitrários para uma folha de apontamentos pré-existente. A finalidade deste ponto de extensão consiste em permitir a um plug-in adicionar mais botões que ajudem o utilizador em determinado passo. Estas botões adicionais são apresentados junto ao ícone da ajuda.
Para utilizar este mecanismo poderá definir qualquer atributo arbitrário na definição do artigo no ficheiro XML da folha de apontamentos. O nome do atributo irá corresponder a atributos que tenham sido contributos em extensões para org.eclipse.ui.cheatsheets.cheatSheetItemExtension. Consulte a documentação sobre pontos de extensão para mais detalhes.
Trabalhar
com folhas de apontamentos
Criar folhas de apontamentos compósitas
Directrizes de Criação
ponto de extensão org.eclipse.ui.cheatsheets.cheatSheetContent
Especificação
do ficheiro de conteúdo das folhas de apontamentos