CCOOMMOO CCOONNSSTTRRUUIIRR AARRQQUUIIVVOOSS DDEE AAJJUUDDAA:: UUMM GGUUIIAA RRÁÁPPIIDDOO EE PPRRÁÁTTIICCOO

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

COMO CONSTRUIR ARQUIVOS DE AJUDA – W.C. RODRIGUES 1

11 CCOONNSSTTRRUUIINNDDOO OO AARRQQUUIIVVOO DDEE AAJJUUDDAA PPAARRAA SSUUAA AAPPLLIICCAAÇÇÃÃOO 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.

COMO CONSTRUIR ARQUIVOS DE AJUDA – W.C. RODRIGUES 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)

COMO CONSTRUIR ARQUIVOS DE AJUDA – W.C. RODRIGUES 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) (dynamic-link 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()

COMO CONSTRUIR ARQUIVOS DE AJUDA – W.C. RODRIGUES 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ção2 Descrição3

# (Cerquilha) Especifica a string do contexto, ou seja, o identificador do tópico, que 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.

$ (Sifrão) Especifica o título do tópico. Máximo de 127 caracteres, podendo ser utilizado qualquer caractere.

K (letra K maiúscula)

Especifica as palavras chaves que serão exibidas no índice da ajuda. As palavras-chave são opcionais, podendo ser utilizada quantas palavras quiser por tópico, separando-as por ponto e vírgula(;) e coom limite máximo de 255 caracteres

+ (sinal de mais) Especifica a seqüência de pesquisa e a ordem de navegação dos botões >> e <<.

Duplo subilinhado Especifica um link (salto). Quando o texto e clicado o mecanismo da dá o salto para o tópico especificado.

Sublinhado simples Exibe numa janela Pop-Up um tópico especificado pelo texto oculto.

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

COMO CONSTRUIR ARQUIVOS DE AJUDA – W.C. RODRIGUES 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).

COMO CONSTRUIR ARQUIVOS DE AJUDA – W.C. RODRIGUES 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

COMO CONSTRUIR ARQUIVOS DE AJUDA – W.C. RODRIGUES 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.

COMO CONSTRUIR ARQUIVOS DE AJUDA – W.C. RODRIGUES 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" End Sub 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 End Sub 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

COMO CONSTRUIR ARQUIVOS DE AJUDA – W.C. RODRIGUES 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 End Sub No evento Click do Form digite: Private Sub Form_Click() Exibir_AjudaAjuda Me End Sub 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)) End Sub 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))

COMO CONSTRUIR ARQUIVOS DE AJUDA – W.C. RODRIGUES 10

End Sub 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 End Sub