Folhas de apontamentos compósitas

As Páginas de anotações compostas facultam orientação através de um problema complexo, decompondo esse problema num conjunto de tarefas menores. As páginas de anotações compostas são registadas através da utilização dos pontos de extensão  org.eclipse.ui.cheatsheets.cheatSheetContent.

Formato de ficheiros de conteúdo

O conteúdo da folha de apontamentos compósita propriamente dito está definido num ficheiro separado que está em conformidade com a  especificação do ficheiro de conteúdo da folha de apontamentos compósita. O ficheiro de conteúdo é um ficheiro XML e consiste num conjunto de tarefas organizadas em grupos numa estrutura em árvore.

A <compositeCheatsheet> é o elemento raiz de uma página de anotações composta. Terá uma única tarefa de raiz que pode ser uma <task> ou um <taskGroup>. Os elementos <taskGroup> podem ter um ou mais elementos descendentes e cada um deles pode ser <task> ou <taskGroup>. Uma <task> não contém tarefas descendentes.

As tarefas e os grupos de tarefas podem conter elementos <intro>, que contêm o texto a que será apresentado antes de a tarefa ser iniciada e elementos <onCompletion>, que contêm o texto a que será apresentado após a tarefa ser concluída. Ambos os elementos <intro> e <onCompletion> podem conter marcações de formato de texto. No exemplo abaixo, os separadores <b> e </b> são utilizados para que o texto seja apresentado a negrito.

As tarefas podem também conter elementos <param>. Uma tarefa de página de anotações pode conter qualquer um dos seguintes parâmetros: "id" é o id de uma página de anotações registada, "path" é o caminho relativo ou a URL do ficheiro de conteúdo da página de anotações e "skipIntro" is  é um parâmetro booleano que, caso seja verdadeiro, leva a que a página de anotações inicie no primeiro passo, em vez de iniciar na introdução. Têm de ser especificados o "id" ou o "path", mas nunca os dois.

Um nó <dependency> da tarefa "B" para a tarefa "A" representa um requisito de que a tarefa A seja concluída antes de a tarefa B poder ser iniciada.

Parâmetros das tarefas de folhas de apontamentos

Se uma tarefa tiver um tipo = "cheatsheet", quando esta for iniciada, será aberta uma folha de apontamentos. Existem três parâmetros possíveis para uma tarefa de folha de apontamentos.

Nome do parâmetro  Descrição
id O id de uma folha de apontamentos registada através da utilização do ponto de extensão org.eclipse.ui.cheatsheets.cheatSheetContent. Identifica a folha de apontamentos que será associada a esta tarefa. Deverá ser especificado o id ou o parâmetro do caminho (mas nunca ambos).
path O URL de um ficheiro de conteúdo de folha de apontamentos. Poderá ser um URL absoluto ou relativo ao ficheiro de conteúdo para a folha de apontamentos compósita. Se tanto o id quanto o caminho estiverem especificados, o caminho será utilizado para localizar o ficheiro de conteúdo e o parâmetro id será ignorado.
showIntro Um parâmetro booleano cujo valor predefinido é true. Caso seja "false" a folha de apontamentos, ao ser iniciada, irá apresentar inicialmente o primeiro passo em vez de apresentar a introdução.

Exemplo de uma página de anotações composta

O ficheiro apresentado abaixo é um exemplo de como criar uma folha de apontamentos compósita a partir de folhas de apontamentos existentes. Este ficheiro apresenta o procedimento para criar grupos de tarefas e para tornar as tarefas passíveis de serem avançadas.

<?xml version="1.0" encoding="UTF-8"?>
<compositeCheatsheet name="Composite cheat sheet example">
    <taskGroup name= "Composite cheat sheet example">
         <intro> This is an example of a <b>composite cheat
sheet</b> built from existing cheat sheets.
                 <br/><br/>You can select a task to work on either
by following the hyperlinks or by
                 selecting a task in the tree. 
  </intro>
         <onCompletion>Congratulations you have completed all the
tasks.</onCompletion>
         <task kind="cheatsheet" name= "Branching and merging
using CVS" skip="true">
              <param name = "id" value =
"org.eclipse.platform.cvs_1" />
              <intro>This cheat sheet is intended for CVS users. If you
are not using CVS or do
              not intend to branch and merge you may skip this task.
  </intro>
               <onCompletion>Congratulations you now know how to branch
and merge.</onCompletion>
             </task>
         <taskGroup name= "Create Java Projects" kind =
"sequence">
             <intro> First you will learn how to create a simple java
project, then you will create
             an java project which uses SWT.
             <br/><br/>This task group is a sequence which means
that
             if you click on the subtask "Standalone SWT Application"
it will not let that task be started
             until "Create a java project" has been completed.
  </intro>
              <onCompletion>Congratulations you have built both Java
applications.</onCompletion>
         <task kind="cheatsheet" name= "Create a java
project" id = "createJavaProject">
             <param name="id" value =
"org.eclipse.jdt.helloworld"/>
                 <param name="showIntro" value =
"false"/>
                 <intro>This cheat sheet walks through the process of
creating a simple hello world application.
                        The cheat sheet can launch wizards to create a new
project and a new class.
  </intro>
             <onCompletion>Congratulations you have succeeded in creating
a hello world application</onCompletion>
             </task>
             <task kind="cheatsheet" name= "Standalone SWT
Application">
                  <intro>Eclipse plugins which contribute to the user
interface use The Standard Widget Toolkit (SWT).
                        This task guide can be used to learn more about SWT.
  </intro>
                  <param name = "id" value =
"org.eclipse.jdt.helloworld.swt" />
                  <onCompletion>Congratulations you have succeeded in
creating an SWT application.</onCompletion>
             </task>
    </taskGroup>
    </taskGroup>
</compositeCheatsheet>

Extensibilidade da Página de Anotações Composta - Provisional no Eclipse 3.2

As páginas de anotações compostas são extensíveis. Contudo, no Eclipse 3.2 esta extensibilidade é provisional e as classes podem alterar-se antes de se tornarem API. O suporte das páginas de anotações compostas pode ser expandido através da utilização do ponto de extensão org.eclipse.ui.cheatsheets.cheatSheetContent, que tem dois elementos novos, o taskEditor e o taskExplorer, que permitem a contribuição de editores e exploradores de tarefas.

A contribuição de um editor de tarefas define um novo tipo de tarefa que é apresentada na secção de detalhes de tarefas. Para contribuir com um editor de tarefa, implemente uma subclasse concreta do  TaskEditor, e  adicione o elemento taskEditor ao plugin.xml.

A representação do explorador de tarefas também é configurável através de um ponto de extensão. É incluído um explorador de árvore com a plataforma Eclipse. Por predefinição, o explorador de uma página de anotações composta quando é aberto tem a forma de uma árvore. Um atributo no elemento <compositeCheatSheet> permite que essa predefinição seja substituída. Se estiver registado mais do que um explorador, o menu ver irá conter uma opção de menu para comutar entre exploradores. Para contribuir com um explorador de tarefa, implemente uma subclasse concreta do TaskExplorer, e adicione um elemento taskExplorer ao plugin.xml.

Ligações relacionadas

Trabalhar com folhas de apontamentos
Trabalhar com folhas de apontamentos compósitas
Criar folhas de apontamentos
Directrizes de Criação
Especificação do ficheiro de conteúdo das folhas de apontamentos compósitas
ponto de extensão org.eclipse.ui.cheatsheets.cheatSheetContent