Qt → Widgets → Help

Definição de um mecanismo que ajude na inserção de help sensível a contexto nos aplicativos baseados em TerraLib e que usem o framework de aplicativos.

A idéia é usar o ferramental do Qt para apresentar as páginas referentes a cada ajuda. Nesse caso, existem 3 possibilidades de solução:

Usando o qAssistant. (*)
Não usando o qAssistant, mas usando o framework de help do qt.
Usando o framework do qt com as janelas já customizadas para o help. (Essa solução precisa ser investigada.)

Design

HelpManager : singleton que contém um ponteiro para um HelpManagerImpl. É uma fachada para chamadas dos métodos da implementação. NÃO tem a propriedade do ponteiro.

HelpManagerImpl : interface para implementação de classes que podem mostrar help e inserir novos projetos de help.

AssistantHelpManager : Especialização do HelpManagerImpl que usa o qAssistant.

HelpPushButton : QPushButton que apresenta o documento help associado no click de mouse.

From Theory to Practice

Para utilizar o ambiente de Help, primeiramente precisamos definir os projetos do help. O Qt usa ferramentas auxiliares para gerar arquivos que contém a especificação de todos os arquivos de help, bem como algumas customizações como icones, palavras-chave, about…

Antes de serem gerados os arquivos compactados, é necessário descrevê-los, por meio de arquivos xml, que serão parseados.

Projeto do help

A primeira coisa é definir o projeto do help. A estrutura de um arquivo de projeto de help é a seguinte:

<?xml version="1.0" encoding="UTF-8"?>
 <QtHelpProject version="1.0">
     <namespace>dpi.inpe.br.terraview.5.0</namespace>
     <virtualFolder>doc</virtualFolder>
     <customFilter name="TerraView 5.0">
         <filterAttribute>terraview</filterAttribute>
         <filterAttribute>5.0</filterAttribute>
     </customFilter>
     <filterSection>
         <filterAttribute>terraview</filterAttribute>
         <filterAttribute>5.0</filterAttribute>
         <toc>
             <section title="TerraView Manual" ref="animation.htm">
                 <section title="Teste 1" ref="associando_arquivos_sites.htm"/>
                 <section title="Teste 2" ref="atribuir_dado_localizacao.htm"/>
                 <section title="Teste 3" ref="animation.htm"/>
             </section>
         </toc>
         <keywords>
             <keyword name="teste1" ref="associando_arquivos_sites.htm"/>
             <keyword name="teste2" ref="atribuir_dado_localizacao.htm"/>
             <keyword name="teste3" ref="animation.htm"/>
         </keywords>
         <files>
             <file>*.htm</file>
         </files>
     </filterSection>
 </QtHelpProject>

Maiores detalhes sobre o significado de cada tag podem ser encontrados no manual de usuário do Qt4. Definido o arquivo de projeto do help, precisamos gerar o binario compactado para que o qt consiga carregá-lo. Isso é feio usando-se o seguinte comando:

qhelpgenerator doc.qhp -o doc.qch

Supondo que o arquivo de projeto se chame doc.qhp e o de saída seja doc.qch.

Além desse arquivo, precisamos definir um arquivo com a coleção de projetos que serão usados. Alguma coisa parecida com:

<?xml version="1.0" encoding="utf-8" ?>
<QHelpCollectionProject version="1.0">
    <assistant>
      <title>TerraView 5.0 Help</title>
#      <startPage></startPage>
      <currentFilter>TerraView 5.0</currentFilter>
      <applicationIcon>../../images/png/128x128/terralib_logo_128x128.png</applicationIcon>
#      <enableFilterFunctionality>true</enableFilterFunctionality>
 #     <enableDocumentationManager>false</enableDocumentationManager>
      <enableAddressBar visible="true">true</enableAddressBar>
      <cacheDirectory base="collection">../../doc/doc_test/generated</cacheDirectory>
      <aboutMenuText>
         <text>About TerraView 5.0 ... </text>
         <text language="pt">Sobre TerraView 5.0 ...</text>
      </aboutMenuText>
      <aboutDialog>
         <file>about.txt</file>
         <file language="en">sobre.txt</file>
         <icon>../../images/png/128x128/terralib_logo_128x128.png</icon>
      </aboutDialog>
    </assistant>
    <docFiles>
      <generate>
        <file>
          <input>doc.qhp</input>
          <output>doc.qch</output>
        </file>
      </generate>
      <register>
        <file>doc.qch</file>
      </register>
    </docFiles>
</QHelpCollectionProject>

Assim como o projeto, a coleção tem uma série de customizações próprias e pode conter vários projetos, como pode ser visto sob a tag docFiles. O próximo passo é parsear o arquivo e gerar um arquivo que pode ser usado no Qt. Isso é feito usando-se o comando:

qcollectiongenerator mycollection.qhcp -o mycollection.qhc

Feito isso, o help já pode ser inserido e usado pelo qAssistant.

Usando o HelpManager

Primeiramente é necessário abrir o arquivo de help pelo assistant. Isso é feito internamente pelo AssistantHelpManager. A princípio o aplicativo terá um arquivo de coleção de projetos que será usado. A essa coleção podemos registrar novos arquivos de projeto.

Para usar o HelpManager, primeiro registrar um HelpManagerImpl:

  te::qt::widgets::AssistantHelpManagerImpl* impl = new te::qt::widgets::AssistantHelpManagerImpl(0);
  te::qt::widgets::HelpManager::getInstance().setMgerImpl(impl);

Para dizer ao manager qual a página deve ser usada:

    te::qt::widgets::HelpManager::getInstance().showHelp("qthelp://dpi.inpe.br.terraview.5.0/doc/associando_arquivos_sites.htm");

Para registrar um novo arquivo de projeto aos já existentes.

  te::qt::widgets::HelpManager::getInstance().appendDoc("docplugin.qch");

Para dizer ao botão qual a página a ser exibida:

  te::qt::widgets::HelpPushButton* help_btn = new te::qt::widgets::HelpPushButton(0);
  help_btn->setPageReference("qthelp://plugintest.terraview.5.0/doc/createTable.htm");