Descrevendo e Empacotando Conteúdo da Ajuda Contextual

A Ajuda contextual é descrita pela associação do id de contexto declarado no código da UI com uma descrição e uma lista de links a tópicos relacionados na ajuda on-line.   Essas associações são feitas dentro de um arquivo XML.  Você pode criar qualquer número de arquivos XML contendo associações da ajuda contextual para cada plug-in.   A descrição e os links para cada ID de contexto são feitos dentro dos elementos <context> no arquivo XML.  Cada elemento de contexto pode ter um elemento <description> opcional que é utilizado para descrever o objeto da UI e qualquer quantidade de elementos <topic> que efetuam o link à documentação on-line.

Desde a 3.1, os elementos do contexto podem substituir opcionalmente o título padrão utilizado para apresentar as informações da ajuda de contexto na visualização Ajuda.

<contexts>
	<context id="panic_button" title="Panic Button Title">
		<description>Este é o botão de pânico.</description>
		<topic href="tasks/pushing_the_panic_button.htm" label="Pressionando o botão de pânico"/>
		<topic href="reference/panic_button.htm" label="Referência do Botão de Pânico"/>
	</context>
	...
</contexts>

Depois de descrever os contextos no arquivo (ou arquivos) XML, você estará pronto para fazer referência aos arquivos de contexto no manifesto do plug-in.  Observe que o ID de contexto não foi especificado completamente acima.  Isso é permitido, desde que o arquivo de contexto esteja contribuído no manifesto do plug-in que definiu o ID do contexto.  Em outras palavras, o ID do contexto é resolvido para o ID do plug-in que contribuiu com o arquivo XML.  

Um plug-in contribui com arquivos de contexto utilizando o ponto de extensão org.eclipse.help.contexts.  

   <extension point="org.eclipse.help.contexts">
      <contexts name="myContextHelp.xml"  />
   </extension>

É possível fazer referência a arquivos de contexto de outros plug-ins incluindo-se o atributo plugin.  Isso permite agrupar toda a documentação, incluindo ajuda contextual, em um plug-in, e fazer referência a ele a partir do plug-in do código da UI ou de algum outro plug-in relacionado.

   <extension point="org.eclipse.help.contexts">
      <contexts name="myContextHelp.xml" plugin="com.example.helpExample"  />
   </extension>

Como você pode ver, há uma grande flexibilidade para a organização de seus contexts em um ou mais arquivos contidos em um ou mais plug-ins.  A principal consideração é que os IDs de contexto nos arquivos sejam resolvidos corretamente.  Se você não especificar completamente um ID de contexto, será necessário contribuir com arquivos XML de contexto no plug-in que declarou os IDs de contexto.  Se utilizar IDs de contexto completos no arquivo XML de contexto, você terá flexibilidade total na localização dos arquivos XML e qual plug-in contribui com os contextos.

Ajuda Contextual de Vários Plug-ins

Outro nível de flexibilidade é a habilidade de contribuir com a ajuda contextual para o mesmo id de contexto de diferentes plug-ins.  Isto será útil, por exemplo, se houver conjuntos de plug-ins de documentação diferentes que possam ou não ser instalados em uma configuração do usuário.  Isso permite que cada plug-in de documentação declare seus contextos independentemente.  O usuário final verá o conteúdo da ajuda contextual mesclado de todos os plug-ins que contribuíram com contextos para o ID do widget.

Observe que é necessário utilizar o ID de contexto completo para o widget, uma vez que nenhum dos plug-ins de documentação declarou o ID de contexto.  Quando vários plug-ins contribuem com a ajuda contextual para o mesmo ID de contexto, o conteúdo definido no plug-in que declarou o contexto (o plug-in da UI) é mostrado em primeiro lugar.  Descrições e links adicionais são anexados sem ordem especificada.

Conteúdo Dinâmico

O conteúdo dinâmico está disponível para a ajuda de contexto na forma de filtros nos links dos tópicos de ajuda. Por exemplo, você pode querer que um link de tópico seja exibido na ajuda do contexto apenas ao ser executado em um determinado sistema operacional.