Folhas de Dicas

As folhas de dicas são visualizações especiais que ajudam a guiar o usuário por uma ´serie de tarefas complexas para alcançar um objetivo geral. Por exemplo, uma folha de dicas pode ser utilizada para ajudar a guiar o usuário por todas as etapas necessárias para criar, compilar e executar um simples programa Java. As folhas de dicas são ativadas a partir do item de menu Ajuda>Folhas de Dicas.... As folhas de dicas também podem ser ativadas a partir de uma página de introdução.

As folhas de dicas são definidas utilizando o ponto de extensão de org.eclipse.ui.cheatsheets.cheatSheetContent. O conteúdo da folha de dicas é definido em um arquivo separado para que possa ser traduzido mais facilmente para outros idiomas.

Contribuindo com uma Folha de Dicas

Contribuir com uma folha de dicas é muito simples. Vamos observar uma folha de dicas contribuída pelo JDT para construir um aplicativo Java simples.

<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>
	...
Muito parecida com outras contribuições do workbench, um nome, uma descrição e um id podem ser especificados para a folha de dicas. O nome a descrição são mostrados quando o usuário acessa a lista Ajuda>Folhas de Dicas.... Uma categoria para a folha de dicas também pode ser definida se você desejar colocar várias folhas de dicas em um agrupamento lógico. Se nenhuma categoria estiver especificada, a folha de dicas aparecerá na categoria Outras.

Diálogo da Folha de Dicas

Itens da Folha de Dicas

O verdadeiro trabalho das folhas de dicas é feito no arquivo de conteúdo. O arquivo de conteúdo é um arquivo XML cujo nome e local são especificados no atributo contentFile. O caminho para o arquivo é relativo para o diretório do plug-in. (Observe a utilização da variável $nl$ no nome do diretório, que significa que o arquivo estará localizado em um diretório específico do idioma nacional do ambiente de destino.)

O formato do arquivo em si inclui informações gerais sobre a folha de dicas, seguidas por uma descrição de cada etapa (chamado um item) que o usuário executará. Um item é apenas uma descrição detalhada da etapa que o usuário deve seguir. No entanto, um item também pode especificar uma ação que pode ser executada para executar a etapa de interesse do usuário. Vamos observar a primeira parte do arquivo de conteúdo (HelloWorld.xml) para a folha de dicas 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 ao tutorial do Hello, World Java.
Ele ajudará você a construir o famoso aplicativo "hello world" e a testá-lo. Você criará um projeto Java e uma classe java que imprimirá o "hello world" no console ao executar.
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>
Selecione Janela->Abrir Perspectiva->Java na barra de menus, na
parte superior do workbench.
Esta etapa altera a perspectiva para configurar o workbench do Eclipse para implementação Java.
Você pode clicar no botão "Clicar para Executar" para abrir a perspectiva "Java" automaticamente.
				</description>
  </item>
...

Folha de dicas java simples

O título e as informações de introdução são mostrados na parte superior da folha de dicas. Em seguida, os itens são descritos. O primeiro item para esta folha de dicas descreve como abrir a perspectiva Java. Melhor ainda, o atributo action especifica uma classe que pode ser utilizada para executar a ação em benefício do usuário. A classe deve implementar IAction. Isso é bem conveniente, já que permite a reutilização das classes de ação gravadas para as contribuições de menu ou da barra de ferramentas.

A classe para a ação pode opcionalmente implementar ICheatSheetAction se a ação utilizar parâmetros ou precisar estar ciente da folha de dicas e seu estado. Neste caso, a ação receberá uma matriz de parâmetros e uma referência para ICheatSheetManager para que possa pedir informações adicionais sobre a folha de dicas. Quaisquer parâmetros necessários podem ser transmitidos para o método de execução da ação utilizando os atributosparamN.

É bastante recomendável que as ações chamadas das folhas de dicas relatem um resultado de sucesso/falha se houver a possibilidade da execução da ação falhar. (Por exemplo, o usuário pode cancelar a ação a partir do diálogo.) Consulte IAction.notifyResult(boolean) para obter detalhes adicionais.

Os itens não têm que definir ações. Se o seu item deve ser executado manualmente pelo usuário, você não precisa especificar uma ação. A seguir, a terceira etapa da folha de dicas Java, que meramente explica ao usuário como codificar o aplicativo simples. Quando nenhuma ação está especificada, a descrição do item deve instruir o usuário a pressionar o botão apropriado depois que a tarefa tiver sido concluída.

<item
	href="/org.eclipse.jdt.doc.user/tasks/tasks-54.htm"
	title="Incluir uma linha System.out.println no seu método principal">
	<description>
Agora que você tem a sua classe HelloWorld,
No método "public static void main", inclua a seguinte instrução:  System.out.println("Hello world!"); e salve suas alterações. Pressione o botão "clicar ao concluir" a seguir quando terminar.
	</description>
  </item>
Os atributos adicionais controlam se o item pode ser ignorado completamente e que documento deve ser ativado se o usuário pedir ajuda durante a etapa. Consulte a documentação do ponto de extensão de org.eclipse.ui.cheatsheets.cheatSheetContent para obter uma descrição de todos os atributos que podem ser definidos dentro de uma folha de dicas.
Subitens

Os subitens podem ser definidos para organizar melhor a apresentação de um item. Diferente dos itens, os subitens não têm que ser visitados em uma ordem específica. Os subitens também podem definir ações que executam automaticamente a subtarefa para o usuário. As ações do subitem são descritas da mesma maneira que as ações do item.

Expressões Condicionais e Variáveis da Folha de Dicas

As expressões condicionais podem ser utilizadas para definir elementos da folha de dicas cujo conteúdo ou comportamento depende de uma condição específica ser true. As condições são descritas no elemento condition de um subitem, utilizando valores de cadeia arbitrária que são correspondidos no atributo when para cada opção. As condições normalmente fazem referência às variáveis da folha de dica utilizando a forma ${var} em que var refere-se ao nome de uma variável da folha de dica. Alguns exemplos simples ajudarão a demonstrar como as expressões condicionais funcionam.

Subitens condicionais podem ser utilizados para escolher um subitem de uma lista de possíveis subitens. Somente o primeiro subitem cujo atributo when corresponde ao atributo de condição é incluído na folha de dica. Por exemplo:

<item ...>
	<conditional-subitem condition="${v1}">
		<subitem when="a" label="Step for A." />
		<subitem when="b" label="Step for B." />
	</conditional-subitem>
  </item>
Este item especifica dois suitens possíveis que dependem do valor da variável v1. Se o valor da variável for a, o primeiro subitem será incluído. Se o valor da variável for b, o segundo subitem será incluído. Se a variável não tiver nenhum desses valores, ela é considerada um erro.

Ações condicionais são semelhantes aos subitens condicionais. O elemento perform-when especifica uma condição para executar uma ação em uma lista de possíveis ações. A condição é descrita do mesmo jeito, utilizando uma cadeia arbitrária que freqüentemente faz referência a uma variável. A ação cujo atributo when corresponde à condição é a que será executada. 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 ação a ser executada é escolhida com base no valor da variável v1. Se o valor da variável não for a ou b, ela é considerada um erro.
Subitens Repetidos

Os subitens repetidos descrevem um subitem que pode ser expandido para 0, 1 ou mais subetapas semelhantes. As subetapas são individualizadas, utilizando a variável ${this} especial. Essa variável será substituída pelos valores especificados no atributo values. O atributo values é uma cadeia de valores que são separados por vírgulas. Uma variável que é expandida para uma lista de valores pode ser utilizada no atributo de valores. Por exemplo:

<item ...>
	<repeated-subitem values="${v1}">
		<subitem label="Step ${this}" />
	</repeated-subitem>
  </item>
Se o valor da variável for 1,b,three, três subitens aparecerão na folha de dicas, cada uma com uma etiqueta exclusiva ("Etapa 1," "Etapa b," "Etapa três"). A variável pode ser utilizada na etiqueta ou no valor de parâmetro de ação. Também pode ser acessada da ICheatSheetManager enquanto a ação está em execução.

Listeners da Folha de Dicas

Em alguns casos, você pode desejar alterar outras partes da sua UI se uma folha de dicas estiver ativa. Por exemplo, você pode ter um editor que mostra anotações especiais se uma folha de dicas estiver guiando o usuário por uma tarefa de edição. Nesse caso, um listener pode ser especificado como um atributo da folha de dicas. O atributo do listener deve ser o nome completo de uma classe Java que tem como subclasse CheatSheetListener. Os listeners receberão notificações junto com um ICheatSheetEvent quando houver uma alteração no ciclo de vida da folha de dicas, como quando ele abre, fecha ou é concluído.

Contribuindo com Atributos para uma Folha de Dicas Existente

A extensão de org.eclipse.ui.cheatsheets.cheatSheetItemExtension pode ser utilizada para contribuir com atributos arbitrários para uma folha de dicas preexistente. A finalidade desse ponto de extensão é permitir que um plug-in inclua botões adicionais que ajudarão o usuário em uma determinada etapa. Esses botões adicionais são exibidos ao lado do ícone de ajuda.

Para utilizar esse mecanismo, é possível definir qualquer atributo arbitrário dentro de uma definição de item no arquivo XML da folha de dicas. O nome do atributo será correspondido em qualquer atributo contribuído nas extensões para org.eclipse.ui.cheatsheets.cheatSheetItemExtension. Consulte a documentação do ponto de extensão para obter detalhes adicionais.