Criando um arquivo de Ajuda - Passo a Passo

Em um artigo anterior - HELP - HTML HELP - já mostramos como criar um arquivo de ajuda no padrão HTML. Embora tenha sido criado para substituir os arquivos de ajuda no padrão Windows, parece que a coisa ainda não decolou.(Nem tudo que a Microsoft toca vira ouro...)  Vamos então mostrar agora como criar um arquivo de ajuda no padrão Windows - WinHelp. 

 O que é um arquivo de ajuda no padrão Windows ?

Um arquivo de ajuda no padrão Windows é um arquivo com extensão HLP o qual é composto dos seguintes componentes:

  1. O arquivo de projeto da Ajuda -  Um arquivo de projeto com extensão .HPJ
  2. O arquivo de tópicos - Um arquivo de com extensão .RTF que contém a ajuda
  3. O arquivo de conteúdo da ajuda - Um arquivo com extensão .CNT 

O arquivo de projeto(.HPJ) e o arquivo de conteúdo(.CNT) são arquivos do tipo texto, e podem ser criados em qualquer editor de textos. Já o arquivo que contém a ajuda(.RTF) é um arquivo no formato Rich-Text que pode ser criado por qualquer programa que dê suporte ao formato RTF.(Word , WordPerfect,  etc...).

Estes arquivos possuem instruções especiais que controlam a construção e o comportamento do arquivo de ajuda. Após criar estes arquivos basta compilar e gerar o arquivo de ajuda ( Você pode incluir outros tipos de arquivos : .BMP , .GIF , etc...)

O que você vai precisar para criar o seu Help

O  coração do seu sistema de ajuda será o arquivo RTF . Ele conterá todo o texto que comporá o seu HELP por isso você vai precisar de um editor que de suporte aos arquivos RTF  O Word funciona muito bem, já o WordPad não suporta todas as capacidades de formatação necessárias. 

Para montar o arquivo de projeto ( HPJ) você pode usar qualquer editor de textos, até o bloco de notas serve.  

A ferramenta usada para editar e compilar os arquivos de ajuda é o utilitário - Microsoft Help WorkShop - Hcw.exe - que acompanha o VB 5.0 . (Você pode usar também o HC31.exe que acompanha o VB 3 ou o HC.exe que acompanha o VB 4.0 )

Antes de criar o seu projeto ou o arquivo de conteúdo você vai precisar criar o texto de ajuda com o texto do seu Help e vai utilizar alguns caracteres e atributos especiais que irão formatar e preparar o relacionamento entre os diversos tópicos criando links entre eles.

Caracteres especiais e atributos de texto usados no seu arquivo de ajuda

Atributo Definição
# Define o identificador do tópico que será usado na referência ao tópico
$ Determina o título do  tópico
K Define uma entrada no índice ou um conjunto de entradas
+ Define a ordem do tópico na sequência para navegação
Duplo sublinhado ( ======= ) Determina um salto para outro tópico
Texto escondido Identifica o tópico para onde saltar

Antes de começar a escrever o arquivo com o texto da ajuda você deve definir quais os tópicos que quer apresentar pois cada tópico é separado por uma quebra de página. A medida que for criando o texto você deve utilizar a formatação para dar forma ao Help de maneira uniforme para que o usuário não se confunda.

Criando o seu arquivo de Ajuda

As principais ferramentas que iremos usar são: um editor de texto que suporte o padrão RTF - o Word da Microsoft - e o HCW - Microsoft Help Workshop - que vem como Visual Basic. Instale o Microsoft Help Workshop que se encontra no diretório \Tools\Hcw do CD-ROM do VB. Após a instalação se você executar o aplicativo terá a seguinte tela:

Voce vai usar o Help WorkShop para criar um conjunto de arquivos de ajuda para sua aplicação. Geralmente estes arquivos são: o arquivo de conteúdo (.cnt) e os arquivos de ajuda associados (.hlp). O arquivo de conteúdo é como um arquivo de índice que contém todo o conteúdo de sua ajuda dividido em tópicos. O usuário irá clicar no tópico de conteúdo para receber informações mais detalhadas.

Vamos fazer um exercício para que você se habitue com a utilização dos caracteres especiais usados na criação do arquivo RTF.

Montando um arquivo de ajuda Exemplo

Vamos agora criar três tópicos simples , mais um tópico de conteúdo, criando links entre eles e definindo entradas no índice para cada um deles. 

  1. Abra o Microsoft Word e digite a palavra Tópico 1 
  2. A seguir posicione o cursor exatamente antes da palavra Tópico 1 e insira uma nota de rodapé com o caractere # . Para fazer isto clique no menu Inserir->Notas e digite o caractere # na caixa de texto da nota de rodapé como figura abaixo, clicando a seguir no botão OK.

  1.  Agora no texto da Nota de rodapé que surge digite a palavra Tópico1, como na figura a seguir:

Acabamos de criar um identificador do tópico que será usado pelos outros tópicos que estabelecerem links com este tópico.

  1. Vamos agora criar o Título do Tópico. Este título será exibido na lista de histórico do WinHelp na caixa de diálogo Pesquisa e no menu Bookmark. Posicione o cursor antes da palavra Tópico 1 e insira uma nota de rodapé com caractere $ digitando Tópico 1 no texto da nota de rodapé, como na figura abaixo:

  1. Para criar as palavras chaves usamos o caractere k. As chaves aparecem no índice do arquivo de ajuda e permitem a localização rápida dos tópicos de interesse do usuário. Posicione o cursor antes da palavra Tópico 1 e insira uma nota de rodapé com o caractere k , digitando Tópico1;Tópico 1;Primeiro como na figura a seguir:

  1. Para encerrar este tópico , insira uma quebra de página selecionando no menu Inserir->Quebra... -> Quebra de página . Todas as definições deste tópico terminam na quebra de página . Veja abaixo a figura:

  1. Insira mais dois tópicos nomeados como: Tópico 2 e Tópico 3 exatamente da mesma forma que fizemos com o Tópico 1. Não esqueça de salvar o seu arquivo no formato RTF . Para este exemplo salvamos o arquivo com o nome de topico.rtf. Abaixo temos um resumo das notas de rodapé usadas nos três tópicos:
Caractere Tópico 1 Tópico 2 Tópico 1
# Tópico1 Tópico2 Tópico3
$ Tópico 1 Tópico 2 Tópico 3
k Tópico1;Tópico 1;Primeiro Tópico2;Tópico 2;Segundo Tópico3;Tópico 3;Terceiro

Fazendo a ligações entre os tópicos

Vamos agora criar o arquivo de conteúdo e  fazer as ligações com os tópicos criados. Este tópico contém os títulos e os links para os demais tópicos. O compilador do Help assume que o tópico de conteúdo é o primeiro no arquivo contendo o texto de ajuda , então vamos inserir uma quebra de página no inicio arquivo topico.rtf  e vamos digitar os títulos : Tópico 1 , Tópico 2 e Tópico 3. Vamos também inserir o texto Arquivo de ajuda e a abaixo as palavras : Selecione um tópico para obter ajuda. Veja o resultado a seguir

Fazendo as ligações

Vamos agora mostrar como fazer as ligações entre o arquivo de conteúdo e os demais tópicos.

  1. Selecione a palavra Tópico 1 no arquivo de conteúdo e escolha a opção Formatar->Fonte do menu , selecione a seguir na caixa Estilo de Sublinhado o estilho Sublinhado Duplo e clique em OK. A palavra Tópico 1 deverá aparecer com um duplo sublinhado. Ver figura abaixo:
Selecionando o duplo sublinhado O resultado
  1. A seguir digite a palavra que você usou no arquivo de  tópico 1 com o símbolo # na nota de rodapé -  Nós usamos a palavra Tópico 1 - imediatamente á frente da palavra Tópico 1 , que sublinhamos , do arquivo de conteúdo. (não deve haver espaços) Veja figura a seguir:

Selecione a palavra Tópico 1 digitada e no menu Formatar ->Fonte  selecione a caixa de opção Oculto . Com isto estaremos ocultando a palavra Tópico 1. A palavra com o duplo sublinhado cria um link com o arquivo Tópico 1 através da palavra oculta Tópico 1 , porque esta palavra foi usada como uma string de contexto através do caractere # na nota de rodapé do arquivo Tópico 1. Veja o resultado:

Ocultando a palavra Tópico 1 O resultado
  1. Repita o processo para a palavra Tópico 2 do arquivo de conteúdo.Lembrando que a palavra que cria a ligação e que foi usada como string de contexto é a palavra Tópico 2.
  2. Para a palavra Tópico 3 do arquivo de conteúdo o processo é idêntico, só que ao invés de usarmos o duplo sublinhado na palavra Tópico 3 vamos usar o sublinhado simples. Com isto criaremos um link que faz surgir a ajuda em um menu pop-up.
  3. Se você fez tudo certinho deverá obter o seguinte resultado:

Salve este arquivo com o nome de topico.rtf.

Criando o arquivo de Ajuda

Com o arquivo topico.rtf pronto podemos criar nosso arquivo de ajuda exemplo só para você ver o resultado de tanto trabalho. 

  1. Inicie o Help WorkShop e no menu File selecione New . Você  verá uma janela exibindo duas opções: Help Project e Help Contents. Selecione a primeira opção e clique em OK.
  2. Na janela exibida a seguir informe o nome do seu arquivo de ajuda -  no nosso caso usaremos o nome exemplo - e clique em OK.
  3. Você deverá ver a seguinte tela:

Clique na opção Files...

  1. Na janela a seguir você deverá clicar no botão Add... e informar o nome do arquivo rtf criado clicando no botão OK. No nosso caso selecionamos o arquivo topico.rtf 

  1. Na próxima janela clique no botão Save e Compile para compilar o seu arquivo de ajuda e gerar o arquivo exemplo.hlp.

  1. Após o processamento o Help WorkShop exibe a tela com o resultado da compilação indicando se houve erros e emitindo mensagens de advertências. Veja abaixo:

  1. Feche a janela do resultado da compilação e a janela com o botão Save e Compile e retorne a janela principal do aplicativo. Selecione a opção File -> Run WinHelp.... O sistema exibirá a seguinte janela.

Para ver o Help clique no botão View Help e pronto !! veja o seu arquivo de ajuda funcionando: Vejamos as telas geradas. (Você pode abrir o Help criando sobre o seu ícone)

1-) Ao clicar no botão View Help temos a janela dos tópicos de ajuda exibida como a seguir:

2-) Clicando no botão Conteúdo teremos a janela de conteúdo. Se clicarmos no item Tópico 1 teremos exibida a janela referente a este tópico. Ver figura abaixo

3-) Se você estava curioso para ver o resultado do Tópico 3 onde usamos um sublinhado simples ao invés do duplo sublinhado. Veja a seguir. Ao clicarmos em Tópico 3 ( perceba que temos uma linha pontilhada sublinhando o item) veremos o arquivo de ajuda tópico 3 sendo chamado como uma janela pop up.

 

4-) E para encerrar clicando na aba Localizar obtemos a janela:

Acho que deu para ter uma idéia de como criar uma estrutura padrão para um arquivo de ajuda.

Inserindo Imagens no seu Help

Você pode inserir imagens no formato bmp , dib ou wmf no seu arquivo de help . Para sofisticar mais ainda seu arquivo de ajuda você pode criar hipergráficos - gráficos com áreas com hiperlinks - que ao ser clicado nos leva a determinado assunto. Para isto as figuras devem ser tratadas no aplicativo Shed.exe (Este aplicativo , também chamado de HotSpot Editor - vem junto com o Help WorkShop ) que permite atribuir a determinadas áreas links relacionados com nosso arquivo RTF.

Para isto devemos abrir a figura no Shed.exe e definir a área que irá receber o link. Vejamos como fazer isto:

O aplicativo Shed.exe - Hot Spot Editor Definindo a área com o link para o arquivo de ajuda

{bmc figura.shg}

Onde :

  1.  bmc - indica o alinhamento do gráfico 
  2.  figura.shg - indica o nome da figura criada no Shed.exe (Deve estar no mesmo diretório dos arquivos com extensão HPJ e RTF )

Você pode inserir as figura diretamente no formato bmp, dib ou wmf usando a mesma sintaxe. A única diferença é que elas serão figuras estáticas sem os hiperlinks.

Integrando o arquivo de ajuda com sua aplicação

Depois de criar o seu arquivo de ajuda ( exemplo.hpl ) você precisa integrá-lo com sua aplicação . Vejamos os passos para associar um arquivo de ajuda ao seu programa em tempo de construção. (Neste exemplo estarei usando o projeto do programa video locadora(loca.vbp)  e o arquivo de ajuda video.hlp )

Pronto ! para invocar o arquivo de ajuda basta pressionar a tecla F1 , e ,  se sua aplicação estiver com o foco o arquivo de ajuda irá ser exibido.

Para associar o arquivo de ajuda em tempo de execução , basta  usar a propriedade HelpFile do objeto App , como no código a seguir:

Private Sub Form_Load()

        App.HelpFile = app.Path & "\vide.hlp"

End Sub

Criando a Ajuda sensível ao contexto 

Uma ajuda sensível ao contexto significa que sua aplicação irá chamar tópicos específicos do arquivo de ajuda conforme o contexto que estiver a sua aplicação.

Para fazer este serviço usaremos a propriedade HelpContextID de um dado controle associada a um valor numérico de tópico identificador do Help. Esta propriedade faz a ligação entre o elemento da interface ( formulário, controle , menu) com um tópico relacionado no arquivo de ajuda. Assim se você designar o valor 1000 para a propriedade HelpContextID de uma caixa de texto, quando o usuário selecionar esta caixa de texto e pressionar F1 o VB irá procurar pelo tópico identificado como 1000 (Context ID) no arquivo de ajuda associado a propriedade HelpFile.

Para atribuir um valor a propriedade HelpContextID de um controle ou  Formulário faça o seguinte:

Para atribuir um valor a propriedade HelpContextID de um Menu faça o seguinte:

Obs: Para atribuir valores para um identificador de Tópico ( Context ID) usando o Microsoft Help WorkShop você vair usar a opção MAP. (ver figura abaixo):

Você pode usar também propriedade WhatsThisHelp que permite exibir em uma janela Pop-UP de maneira simplificada mensagens de ajuda ao usuário. Para isto basta atribuir a propriedade WhatsThisHelp de um formulário o valor True. Lembre-se que ao fazer isto você desabilita a ajuda sensível ao contexto.

Para utilizar a ajuda do tipo What´s This Help para um formulário faça o seguinte:

Bem acho que por ora estamos conversados ... !!!