AUTOR: WILLIAM COSTA RODRIGUES

COMO CONSTRUIR ARQUIVOS DE AJUDA: UM GUIA RÁPIDO E PRÁTICO AUTOR: WILLIAM COSTA RODRIGUES 2004

DIREITOS AUTORAIS E LICENÇA DE USO TUTORIAL COMO CONSTRUIR ARQUIVOS DE AJUDA >> Este tutorial poderá ser utilizado livremente, para fins de estudos, porém é vetada a comercialização deste ou de parte deste. A Utilização deste ou de parte deste poderá ser realizada desde que citada a fonte e o site da Lizaro Soft. >> W.C. Rodrigues (Lizaro Soft), detém todos os direitos sobre este tutorial (COMO CONSTRUIR ARQUIVOS DE AJUDA). >> TUTORIAL COMO CONSTRUIR ARQUIVOS DE AJUDA Copyright 2001-2004, W.C. Rodrigues (Lizaro Soft) Lizaro Soft - Inovação em Softwares Web Site: http://www.lizarosoft.ebras.vbweb.com.br E-mails: lizarosoft@ebras.vbweb.com.br

1 1 CONSTRUINDO O ARQUIVO DE AJUDA PARA SUA APLICAÇÃO Inicialmente, você irá precisar de uma dos compiladores da Microsoft para gerar os arquivos no padrão HLP, os mais recentes são HCW que gera arquivos de ajuda na versão 4.0 e com extensão.hlp e o HTML Help que gera arquivos de ajuda com extensão.chm. Os dois compiladores poderão ser baixados no site da Microsoft (o HTML HELP, está em www.microsoft.com/workshop/author/htmlhelp/default.asp (3.99 MB). Um grande exemplo de um projeto de ajuda utilizando HTML Help Workshop pode ser encontrado no site de José Carlos Macorati Site Pessoal www.macorrati.net. Neste capítulo serão demostrados um exemplo de construção de arquivos de ajuda como o compilador HC35 (interface em DOS) que poderão se baixados no nosso site na seção download, além de uma versão Shareware do programa Lizaro Helper Compiler v3.0 - www.lizarosoft.cjb.net. 1.1 Microsoft Help Compiler v3.10 e v3.50 O sistema operacional Windows possui como arquivo de ajuda padrão arquivos com a extensão HLP, que podem ser acessados de várias formas, além de possui um grande facilidade através de links, que permitem saltos entre tópicos. Um arquivo de ajuda é composto dos seguintes arquivos: Arquivo de projeto da Ajuda Arquivo com extensão HPJ; Arquivo de contexto da Ajuda Arquivo com extensão CNT; Arquivo de Texto da Ajuda, contento os tópicos Arquivo com extensão RTF; Arquivos Gráficos (imagens) 1 Arquivos com extensão BMP, SHG, WMF, GIF; JPG. Para criamos os arquivos de projeto de ajuda (projeto.hpj) e contexto da ajuda (contexto.cnt), podemos utilizar qualquer editor de texto que permita salvar, com uma extensão diferentes dos arquivo padrão, algumas sugestões, são: o Bloco de Notas, WordPad, Lizaro Editor v1.0(que pode ser baixado em nosso site), entre outros. Já para a criação do arquivo de texto (arquivo.rtf), recomendamos processadores de texto que suportem todos os formatos RTF (Rich Text Format), por exemplo Word, WordPerfect, StarWriter, etc. Antes de iniciar um projeto de arquivo de ajuda o programador deve ter bem claro e préprojetado em papel, os tópicos que serão redigidos, as imagens que serão utilizadas, os saltos que serão feitos dentro do arquivo de ajuda, etc. Lembre-se a documentação de um programa é tão importante quanto o próprio, pois irá elucidar o usuário no momento de dificuldade no uso do programa. 1.1.1 Projeto da Ajuda (conceitos básico) Um projeto da ajuda, contém alguns tópicos chamados Seções e dentro destas existem as opções. As seções de um projeto de ajuda basicamente são: OPTIONS, WINDOWS, FILES, CONFIG, MAP. Existem outras opções, mas para o exemplo iremos utilizar somente estas. No projeto as seções são especificadas dentro de colchetes. Ex.; [OPTIONS] Dentro de cada seção poderemos encontrar poucas ou várias opções. Abaixo listaremos algumas das opções de cada campo, a descrição e o número máximo de caracteres suportados pelo compilador HC35. 1.1.1.1 Seção OPTIONS Nesta seção estão contidas as informações gerais do arquivo de ajuda a ser criado. BMROOT Especifica a pasta que contém o nome dos arquivos bitmap nomeados em {bmc}, {bml}, e {bmr} referências nos arquivos de tópico (.rtf). Ex.: BMROOT= C:\HELP\BMP ROOT Especifica a pasta onde o compilador deverá procura o arquivo de tópicos (.rtf). Ex.: ROOT=C:\Help\HelpDir. 1 Para os compiladores HC31 e HC35, somente os formatos BMP, SHG e WMF, são suportados, os demais, somente o compilador HCW, suporta.

2 ERRORLOG Especifica o nome do arquivo de erro e/ou comentários gerados após a compilação do arquivo de ajuda. (máximo 8 caracteres no nome, ex.: ERRORLOG=errajuda.txt ou ERRORLOG=errajuda.err). CONTENTS Especifica o tópico inicial do arquivo de ajuda, em geral o tópico da primeira página do arquivo de rtf. (máximo 255 caracteres). CONTENTS=cntAjuda. COMPRESS Especifica como o arquivo de Ajuda deve está comprimido. Os valores são 0 (Nenhuma compressão), 1 (Compressão alta), FALSE (Nenhuma compressão), HIGH (Compressão alta), MEDIUM (Compressão média), NO (Nenhuma compressão), TRUE (Compressão alta), YES (Compressão alta). OLDKEYPHRASE Especifica se o compilador deve usar a tabela de frase de chave existente ou criar uma nova durante a compilação, ou seja, arquivos com extensão.ph. Os valores são: 0 (Recreia o arquivo), 1 (Use o arquivo existente), FALSE (Recreia o arquivo), NO (Recreia o arquivo), OFF (Recreia o arquivo), ON (Use o arquivo existente), TRUE (Use o arquivo existente), YES (Use o arquivo existente). TITLE Especifica o título do arquivo de ajuda, que será exibido na tela do índice e localizar. (máximo de 255 caracteres). COPYRIGHT Exibe na tela de versão a descrição de direitos autorais do arquivo de ajuda (ex.: Copyright 2000, Lizaro Soft). (máximo 50 caracteres). WARNING É o nível de advertência que deverá ser exibida durante a compilacão. Os valores vão de 1 3, onde 1 (Relata somente os erros mais severos), 2 (Relata um número intermediário de erros) e 3 (Relata todos os erros e advertências). REPORT Controla a exibição de mensagens durante o processo de construção. Valores ON e não inserir a opção. Existem outras opções, mas não serão abordadas neste exemplo. 1.1.1.2 Seção WINDOWS Nesta seção estão contidas as informações, da janela do arquivo de ajuda. Para a janela principal dá-se o nome MAIN e para a janela secundária em geral dá-se o nome HOWTO, mas o programador poderá escolher outro nome para está janela. Abaixo segue as especificações de uma janela e dois exemplos. NOMEJANELA= "Titulo da janela da ajuda (máximo 255 caracteres)", (X,Y,largura,altura), sizing, (cor da área do texto), (cor da área do cabeçalho). X= Distância em pixels da janela a esquerda da tela (1024); Y= Distância em pixels da janela do alto da tela (1024); Sizing= 0 (Configurar a janela para o tamanho especificado pelo x, y, largura, e parâmetros de altura) ou 1 (Maximize a janela; ignorando o x, y, largura, e parâmetros de altura). Cor da área do texto= É a cor do fundo da área do texto, segue o padrão RGB; Cor da área do cabeçalho= É a cor do fundo da área do cabeçalho. [WINDOWS] MAIN="Ajuda de Lizaro Helper Compiler v1.0",,,, (255,252,145) O exemplo acima exibe a janela principal de arquivo com o titulo "Ajuda de Lizaro Helper Compiler v1.0", com o tamanho, posição e a cor da área do texto de acordo com as especificações do sistema, somente a cor do cabeçalho é especificada amarelo claro. (Figura 10) HowTo="Passo-a-Passo", (200,200,500,500),0, (255,255,210), (255,128,0) O exemplo acima à janela secundária terá o título "Passo-a-Passo" a disposição da janela é 200 pixels a esquerda, 200 do topo da tela e possui 500 x 500 pixels de largura e altura, respectivamente. O tamanho obedece aos parâmetros de especificação, X,Y, largura e altura, as cores são amarelo bem claro para área do texto e laranja para o cabeçalho. (Figura 11)

3 Figura 1. Aspectos da interface da janela principal do arquivo de ajuda de Lizaro Helper Compiler v1.0 Standard Edition. Figura 2. Aspectos da interface da janela passo-a-passo do arquivo de ajuda de Lizaro Helper Compiler v1.0 Standard Edition. 1.1.1.3 Seção FILES Nesta seção o programador irá listar todos os arquivos de tópicos utilizados para compor o arquivo de ajuda. Poderão ser utilizados quantos arquivos o programador achar necessário, mas atenção quanto maior o número de arquivo maior será dificuldade para atualizá-lo. Quando os arquivo forem salvos deverão Ter no máximo 8 carascters (padrão DOS), pois já que o compilador roda em DOS, as configurações deste sistema operacional deverão ser respeitadas. O exemplo seguinte especifica dois arquivos de tópico: [FILES] HelperSE.rtf hlppopup.rtf 1.1.1.4 Seção CONFIG A seção [CONFIG] contém um ou mais macros que executam ações, como habilitando botões de navegação e registrando funções de bibliotecas de vínculo dinâmico (DLL's) (dynamiclink library). Ajuda do Windows executa as macros quando arquivo de Ajuda é aberto. Por exemplo, para habilitar os botões de navegação (>> e <<) de um arquivo de ajuda basta inserir o seguinte exemplo: [CONFIG] BrowseButtons()

4 1.1.1.5 Seção MAP A seção [MAP] associa strings de contexto (ou nomes alternativos, aliases) com números de contexto para Ajuda sensível a contexto. O número de contexto corresponde para um valor o aplicativo de "pai" passa para Ajuda do Windows a fim de exibir um tópico particular. Esta seção é opcional. A Sintaxe é: Contexto-string Número de contexto onde: Contexto-string Especifica a string de contexto de um tópico no arquivo de Ajuda. A string pode ser qualquer combinação de caracteres, exceto espaços, e devem ser também especificados em um contexto-string Nota de rodapé declaração em algum tópico no arquivo de Ajuda. Número de contexto Especifica o número de contexto para associar com a string de contexto. O número pode estar em um ou outro decimal ou C normal formato hexadecimal. Só um número de contexto pode ser designado para uma string de contexto ou nome alternativo (alias). Designando o mesmo número para mais de uma string de contexto gera um erro de compilação. Pelo menos um espaço deve separar o número de contexto da string de contexto, recomenda-se uma tabulação do teclado (tecla TAB). 1.1.2 Arquivo de Texto (Arquivo de Tópicos) RTF Um arquivo de texto deverá conter certos caracteres especiais, para que o compilador possa transformá-las em saltos, contexto e palavras-chave. Estes caracteres em RTF são demostradas na Tabela 8 abaixo: Tabela 1. Caracteres especiais, atribuição e descrição, para a construção do arquivo texto (tópicos) da ajuda. Atribuição 2 Descrição 3 Especifica a string do contexto, ou seja, o identificador do tópico, que # (Cerquilha) será utilizado pela ajuda para referencia-lo. Máximo de 255 caracteres podendo utilizar letras de A até Z, algarismos, um ponto e um sublinhado. Especifica o título do tópico. Máximo de 127 caracteres, podendo ser $ (Sifrão) utilizado qualquer caractere. Especifica as palavras chaves que serão exibidas no índice da ajuda. As palavras-chave são opcionais, podendo ser utilizada quantas palavras K (letra K maiúscula) quiser por tópico, separando-as por ponto e vírgula(;) e coom limite máximo de 255 caracteres Especifica a seqüência de pesquisa e a ordem de navegação dos botões + (sinal de mais) >> e <<. Especifica um link (salto). Quando o texto e clicado o mecanismo da dá o Duplo subilinhado salto para o tópico especificado. Sublinhado simples Exibe numa janela Pop-Up um tópico especificado pelo texto oculto. Referencia o tópico que o texto sublinhado deverá saltar. Deve ser especificado logo após a(s) palavra(s) sublinhada(s) (duplo ou simples) e Texto oculto com um espaço antes do parágrafo, para não ocultar o parágrafo seguinte. A Figura 12 abaixo demonstra os caracteres especiais, textos sublinhados duplo e texto oculto. A Figura 13 demostra as notas de rodapé referentes os caracteres especiais exibidos na figura 12. 2 Os caracteres especiais #,$,K e +, são utilizado como nota de rodapé, os demais deverão ser utilizado no decorrer do texto. 3 Especificação do tamanho máximo de caracteres são para os compiladores HC31 e HC35

5 Figura 3. Exemplo de caracteres especiais, palavras sublinhada e textos ocultos. Figura 4. Notas de rodapé especificando os caracteres especiais inseridos no texto da Figura 12, são eles # string do contexto do tópico; $ título do tópico e K Palavras-chave. Após o planejamento de um pequeno exemplo de um arquivo tópicos de ajuda, inicie um processador de texto (Word, WordPerfect, StarWriter, etc) e na primeira linha do arquivo antes de insira uma nota de rodapé, como na Figura 14, verifique também a Figura 12 e 13. Figura 5. Telas do Word 97 e do StarWriter 5.1 (respectivamente)para inserção de notas de rodapé com caracteres especiais (personalizados). Não edite os arquivos criados no Word, no WordPad, pois este não possui ferramentas para criar notas de rodapé. Para começar um novo tópico basta inserir um quebra de página. Proceda da seguinte forma no Word acesse o menu Inserir>Quebra..., na tela selecione Quebra de Página e clique em OK, como mostra a Figura 15 abaixo, ou se preferir pressione a tecla Control e Enter ao mesmo tempo(ctrl+enter).

6 Figura 6. Telas do Word 97 e do StarWriter 5.1, para inserir quebra de página (respectivamente) 1.1.2.1 Ativando o mecanismo de salto Como já foi visto na Figura 12 e 13, o arquivo de ajuda, possui formas de referenciar as strings, para que o mecanismo de ajuda possa reconhecê-las. Assim para que o usuário possa saltar do texto que ele está lendo para um texto relacionado, basta marcar a palavra com um duplo sublinhado e em seguida especificar com o nome (string) do contexto (#) onde o mecanismo deverá ir, com na Figura 16. Figura 7. Parágrafo com um duplo sublinhado (link) e palavra oculta, para onde o mecanismo de ajuda deverá ir quando a palavra sublinhada for clicada. Detalhe que entre o final da palavra oculta e o final do parágrafo, existe um espaço, que é recomendado. Para somente abrir uma janela como Pop-Up, somente sublinhe simples a palavra que ativará a janela. No caso de querer o tópico numa a janela alternativa (Passo-a-Passo), basta após do nome do tópico (#), inserir palavra com duplo sublinhado>nome da janela, esta deverá está especificada no projeto da ajuda, com mostra o Seção WINDOWS. Veja a Figura 17. Figura 8. Sintaxe para que o mecanismo da ajuda abra o tópico especificado (OQReg), numa janela secundária. 1.1.2.2 Abrindo o Browser padrão e o Editor de Correio Eletrônico padrão É possível abrir estes dos aplicativo através de um arquivo de ajuda, as sintaxe estão nas Figura 18 e 19 abaixo. A(s) palavra(s) que irão acessar os aplicativo poderão esta sublinhada com sublinhado simples o duplo. Figura 9. Sintaxe para abrir o Browser através do arquivo de ajuda. Figura 10. Sintaxe para abrir o Editor de Correio Eletrônico através do arquivo de ajuda. 1.1.2.3 Inserindo figuras no arquivo de ajuda As imagens quando bem elaboradas, e trabalhadas, dão um belo aspecto ao arquivo de ajuda. O HC31 e HC35, não suportam que as imagens sejam diretamente inseridas no arquivo de

7 texto (tópicos), porém a HCW, já suporta. Outro detalhe é que as imagens não poderão tem o tamanho acima de 60 KB pois geram um erro de falta de memória na compilação e no arquivo de ajuda gera um quadro como mostra a Figura 22. Para referenciar uma imagem, inclua a seguinte String, dento de chaves {bmc nome do arquivo.bmp}. Figura 11. Quadro exibido quando ocorre um erro na compilação do arquivo de ajuda, geralmente quando a imagem tem um tamanho muito grande (acima de 60KB). As Strings mais utilizadas para referenciar imagens são as seguintes: {bmc} = Ajusta a imagem no centro; {bml} = Ajusta a imagem à esquerda; {bmr} = Ajusta a imagem à direita; As imagens poderão ser do tipo Bitmap Windows (BMP), Windows Metafile (WMF) ou ainda compiladas Hypergraphic Bitmap (SHG), que poderão ser criadas através do Microsoft HotSpot. Atenção: Como o compilador HC31 e HC35, são executados no DOS os nomes dos arquivos devem ter no máximo oito letras (8), sem contar a extensão, servindo também para os diretórios dos projetos a serem criados. 1.1.2.4 Outros formatos suportados pelos compiladores HC31 e HC35 Poderão ser inseridas tabelas de formatação simples; Texto com cores diferenciadas; Texto com alinhamento a esquerda, ao centro e a direita; 1.1.2.5 Compilando todos os arquivos Após tudo pronto, basta compilar o projeto da ajuda e em seguida e só realizar os devidos testes, para evitar que a ajuda apresente erros na hora que o usuário acesse-a. Para compilar os arquivo o programa dor tem três alternativas: utilizando HC 31 ou HC35 a partir do DOS (Figura 21), através de um programa editor e compilador como Lizaro Helper Compiler v1.0 (Figura 22) e através do Microsoft Help Workshop (Figura 23) Figura 12. Tela do DOS com a sintaxe para compilação de um projeto de ajuda utilizando os compiladores HC31 ou HC35.

8 Figura 13. Tela de compilação do Lizaro Helper Compiler v1.0 Professional Editon. Figura 14. Tela de compilação do Microsoft Help Workshop. 1.1.2.6 Executando o arquivo de ajuda compilado Existem duas formas de acessar o arquivo de ajuda uma é com o uso da API WinHelp e através do controle CommomDialog, com a seguir: No evento Load de um Form ou no Sub Main, insira o nome do arquivo de ajuda do aplicativo, da seguinte forma: Private Sub Form_Load() App.HelpFile = "C:\Caminho...\Arquivo.hlp"'Especifica o arquivo de ajuda do aplicativo, em geral o caminho é App.Path & "\Arquivo.hlp" ou App.Path & "\Ajuda\Arquivo.hlp" Private Sub smnuajuda_click() CommonDialog1.HelpFile = App.HelpFile 'Especifica o arquivo de ajuda para o controle CommonDialog1.HelpCommand = constante(vide tabela abaixo) 'Executa o comando de acordo a necessidade do programador CommonDialog1.ShowHelp 'Exibe o arquivo de ajuda especificado e de acordo com o comando Tabela 2. Constante e especificações dos comandos utilizados pelo controle CommomDialog Constante Valor Descrição cdlhelpcontext &H1 Exibe a ajuda de um tópico em particular cdlhelpquit &H2 Notifica o aplicativo de Ajuda que o arquivo de Ajuda especificada não está mais em uso cdlhelpindex &H3 Exibe o índice do arquivo de Ajuda especificada cdlhelpcontents &H3 Exibe o tópico de conteúdo no corrente arquivo Ajuda

9 cdlhelphelponhelp &H4 Exibe a ajuda de como usar a ajuda cdlhelpsetindex &H5 Fixa o índice atual para Ajuda de índice múltiplo cdlhelpsetcontents &H5 Designa um tópico específico como o tópico de conteúdo cdlhelpcontextpopup &H8 Exibe um tópico identificado por um número de contexto cdlhelpforcefile &H9 Cria um arquivo de Ajuda que exibe texto em uma só fonte cdlhelpkey &H101 Displays Help for a particular keyword cdlhelpcommandhelp &H102 Exibe a Ajuda para um comando particular cdlhelppartialkey &H105 Chama a mecanismo de procura na Ajuda do Windows 1.1.2.7 Executando Arquivo de Ajuda Através de API no Visual Basic Para abrir arquivos de ajuda é de praxe que utilizemos o conhecido controle ActiveX Commom Dialog, porém se você não quiser utiliza-lo, basta inserir a seguinte API num módulo. Public Declare Function WinHelp Lib "user32" Alias "WinHelpA" (ByVal hwnd As Long, ByVal lphelpfile As String, ByVal wcommand As Long, ByVal dwdata As Long) As Long Public Const HELP_CONTEXT = &H1 'Exibe o tópico de ajuda pelo Número ID Public Const HELP_HELPONHELP = &H4 'Exibe a ajuda do Windows de como utilizar ajuda Public Const HELP_INDEX = &H3 'Exibe o Índice da Ajuda Public Const HELP_QUIT = &H2 'Termina ajuda Public Const HELP_MULTIKEY = &H201& 'Procura por palavras-chave na tabela alternativa da ajuda Public Const HELP_KEY = &H101 'Exibe o Índice da Ajuda Public Sub Exibir_AjudaAjuda(X As Form) Dim Hlp As Long Hlp = WinHelp(X.hwnd, "C:\Windows\Windows.hlp", HELP_HELPONHELP, CLng(0)) 'Exibe o arquivo de ajuda sobre ajuda do Windows No evento Click do Form digite: Private Sub Form_Click() Exibir_AjudaAjuda Me Para finalizar o arquivo de ajuda juntamente com o aplicativo insira as seguinte linhas de código no evento Unload do From: Private Sub Form_Unload(Cancel As Integer) Dim Hlp As Long Hlp = WinHelp(Me.hWnd, "Arquivo de ajuda", HELP_QUIT, CLng(0)) Para exibir um tópico específico, crie a seguinte procedure: Public Sub Ajuda_Topico (X as form, Topico as Long) Dim Hlp as Long Hlp = WinHelp (X.hWnd, "Arquivo de ajuda", HELP_CONTEXT, CLng(Topico))

10 No evento de um botão ou no menu que queira exibir um tópico específico, insira as seguintes linhas: Private Sub cmdajuda_click() Ajuda_Topico me, número 'Onde o número referencia o tópico a ser exibido, Seção MAP