Ajuda autónoma

Se estiver a criar uma aplicação que não se baseie na infra-estrutura do Eclipse, pode da mesma forma utilizar o sistema de ajuda do Eclipse. A aplicação pode colocar em pacote e instalar o sistema de ajuda autónomo, uma versão muito reduzida do Eclipse que tem tudo, excepto o sistema de ajuda que foi retirado. Então, a aplicação poderá fazer chamadas da API a partir do menu Ajuda ou a partir de objectos da UI, para lançar o browser da ajuda. O sistema de ajuda autónomo contém todas as funções do sistema de ajuda integrado, excepto a ajuda de contexto integrado da área de trabalho, a vista ajuda e a ajuda activa. Quando uma aplicação não se baseia em Java ou quando é necessário utilizar a ajuda quando a aplicação não está em execução, é possível utilizar o sistema de ajuda a partir de um shell da ajuda, um shell script ou atalho da área de trabalho e fornecer as opções da linha de comandos em vez de chamas as APIs de Java.

O sistema de ajuda autónomo permite transmitir várias opções que podem ser utilizadas para personalizar os vários aspectos do sistema de ajuda. São suportadas as seguintes opções:

Instalação/empacotamento

Estes passos destinam-se ao integrador do sistema de ajuda e não para visualizar todos os possíveis cenários. Pressupõe-se que toda a documentação é entregue como plug-ins do eclipse e que o utilizador conhece, de uma forma geral, o sistema de ajuda do eclipse.
  1. Descarregue o controlador Binário do Tempo de Execução da Plataforma do eclipse a partir de eclipse.org.
  2. Instale o controlador (descomprimir) num directório sob o directório da aplicação, d:\myApp. Este procedimento irá criar um sub-directório do eclipse, d:\myApp\eclipse, que contém o código necessário para a plataforma do eclipse (que inclui o sistema de ajuda).

Como chamar as classes de ajuda de Java

  1. Certifique-se que d:\myApp\eclipse\plugins\org.eclipse.help.base_[version].jar está no seu caminho da classe, no qual [version] é a versão do plug-in que está a utilizar (por exemplo, org.eclipse.help.base_3.2.0.jar). A classe que utiliza para iniciar, lançar e encerrar o sistema de ajuda é org.eclipse.help.standalone.Help.
  2. Crie uma matriz de objectos String que contenham opções que pretende transmitir para o suporte do sistema de ajuda. Geralmente, a opção eclipsehome é necessária.
    String[] options = new String[] { "-eclipsehome",
    "d:\\myApp\\eclipse" };
  3. Na aplicação, crie uma instância da classe Help ao transmitir estas opções. Este objecto deverá ser retido até ao fim da aplicação.
    Help helpSystem =
    new Help(options);
  4. Para iniciar o sistema de ajuda:
    helpSystem.start(); 
  5. Para invocar a ajuda quando for necessário:
    helpSystem.displayHelp(); 

    Pode ainda chamar a ajuda em ficheiros ou tópicos TOC principais específicos:

    helpSystem.displayHelp("/com.mycompany.mytool.doc/toc.xml");
    helpSystem.displayHelp("/com.mycompany.mytool.doc/tasks/task1.htm");
  6. Para lançar a ajuda sensível ao contexto, chame helpSystem.displayContext(contextId, x, y) onde contextId é um ID de contexto totalmente qualificado. As coordenadas do ecrã, x e y, não são utilizadas actualmente.
  7. No fim da aplicação, para encerrar o sistema de ajuda:

    helpSystem.shutdown(); 

Como chamar a ajuda a partir da linha de comandos

A classe org.eclipse.help.standalone.Help contém um método principal que pode utilizar para lançar a ajuda autónoma a partir da linha de comandos. A sintaxe dos argumentos da linha de comandos é:

-command start | shutdown | (displayHelp [href]) [-eclipsehome eclipseInstallPath] [-data instanceArea] [-host helpServerHost] [-port helpServerPort] [-dir rtl] [platform options] [-vmargs JavaVMarguments]

Um modo simples de visualizar a ajuda é invocar

java -classpath
d:\myApp\eclipse\plugins\org.eclipse.help.base_[version].jar
org.eclipse.help.standalone.Help -command displayHelp

a partir do directório d:\myApp\eclipse, em que version é a versão do plug-in. Para apresentar um ficheiro ou tópico TOC específico utilize

java -classpath
d:\myApp\eclipse\plugins\org.eclipse.help.base_[version].jar
org.eclipse.help.standalone.Help -command displayHelp
/com.mycompany.mytool.doc/tasks/task1.htm

As chamadas anteriores para visualizar a ajuda fazem com que o sistema da ajuda seja iniciado, apresentam a ajuda e mantém-na em execução para parmitir a um utilizador continuar a procurar a ajuda após o comando ser executado. Para controlar o ciclo de vida do sistema de ajuda, utilize os comandos start e shutdown, além do comando displayHelp. Por exemplo, pode chamar

java -classpath
d:\myApp\eclipse\plugins\org.eclipse.help.base_[version].jar
org.eclipse.help.standalone.Help -command start

[Opcional] Instalar um sistema de ajuda autónomo mínimo

A ajuda autónoma não necessita do pacote completo da Plataforma do eclipse. É possível executar a ajuda autónoma com o Binário de Tempo de Execução da RCP tendo os seguintes plug-ins adicionados ao directório eclipse/plugins):

org.apache.lucene
org.eclipse.help
org.eclipse.help.appserver
org.eclipse.help.base
org.eclipse.help.ui
org.eclipse.help.webapp
org.eclipse.tomcat
org.eclipse.ui.forms

Nota: Tem de se certificar que a seguinte linha está presente no ficheiro eclipse/configuration/config.ini:

osgi.bundles=org.eclipse.equinox.common@2:start,
org.eclipse.update.configurator@3:start, org.eclipse.core.runtime@start

Alguns plug-ins de documentação poderão conter dependências em outros plug-ins, geralmente ao especificar os plug-ins necessários no respectivo manifesto. Os plug-ins dependentes também necessitam de ser instalado. Adicionalmente, os plug-ins concebidos para versões do eclipse anteriores à 3.0 requerem implicitamente que o plug-in org.eclipse.core.runtime.compatibility seja apresentado para funcionar.

Para mais informações sobre a personalização do sistema de ajuda, consulte Personalização do produto.