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.
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.