Você está na página 1de 12

COMO CONSTRUIR ARQUIVOS DE AJUDA: UM GUIA RPIDO E PRTICO

AUTOR: WILLIAM COSTA RODRIGUES

2004

DIREITOS AUTORAIS E LICENA DE USO TUTORIAL COMO CONSTRUIR ARQUIVOS DE AJUDA >> Este tutorial poder ser utilizado livremente, para fins de estudos, porm vetada a comercializao deste ou de parte deste. A Utilizao deste ou de parte deste poder ser realizada desde que citada a fonte e o site da Lizaro Soft. >> W.C. Rodrigues (Lizaro Soft), detm 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 - Inovao 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

CONSTRUINDO O ARQUIVO DE AJUDA PARA SUA APLICAO

Inicialmente, voc ir precisar de uma dos compiladores da Microsoft para gerar os arquivos no padro HLP, os mais recentes so HCW que gera arquivos de ajuda na verso 4.0 e com extenso .HLP e o HTML Help que gera arquivos de ajuda com extenso.CHM. Os dois compiladores podero 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 captulo sero demostrados um exemplo de construo de arquivos de ajuda como o compilador HC35 (interface em DOS) que podero se baixados no nosso site na seo download, alm de uma verso 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 padro arquivos com a extenso HLP, que podem ser acessados de vrias formas, alm de possui um grande facilidade atravs de links, que permitem saltos entre tpicos. Um arquivo de ajuda composto dos seguintes arquivos: Arquivo de projeto da Ajuda Arquivo com extenso HPJ; Arquivo de contexto da Ajuda Arquivo com extenso CNT; Arquivo de Texto da Ajuda, contento os tpicos Arquivo com extenso RTF; Arquivos Grficos (imagens)1 Arquivos com extenso 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 extenso diferentes dos arquivo padro, algumas sugestes, so: o Bloco de Notas, WordPad, Lizaro Editor v1.0(que pode ser baixado em nosso site), entre outros. J para a criao 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 prprojetado em papel, os tpicos que sero redigidos, as imagens que sero utilizadas, os saltos que sero feitos dentro do arquivo de ajuda, etc. Lembre-se a documentao de um programa to importante quanto o prprio, pois ir elucidar o usurio no momento de dificuldade no uso do programa. 1.1.1 Projeto da Ajuda (conceitos bsico) Um projeto da ajuda, contm alguns tpicos chamados Sees e dentro destas existem as opes. As sees de um projeto de ajuda basicamente so: OPTIONS, WINDOWS, FILES, CONFIG, MAP. Existem outras opes, mas para o exemplo iremos utilizar somente estas. No projeto as sees so especificadas dentro de colchetes. Ex.; [OPTIONS] Dentro de cada seo poderemos encontrar poucas ou vrias opes. Abaixo listaremos algumas das opes de cada campo, a descrio e o nmero mximo de caracteres suportados pelo compilador HC35. 1.1.1.1 Seo OPTIONS Nesta seo esto contidas as informaes gerais do arquivo de ajuda a ser criado. BMROOT Especifica a pasta que contm o nome dos arquivos bitmap nomeados em {bmc}, {bml}, e {bmr} referncias nos arquivos de tpico (.rtf). Ex.: BMROOT= C:\HELP\BMP ROOT Especifica a pasta onde o compilador dever procura o arquivo de tpicos (.rtf). Ex.: ROOT=C:\Help\HelpDir.
Para os compiladores HC31 e HC35, somente os formatos BMP, SHG e WMF, so suportados, os demais, somente o compilador HCW, suporta.
1

COMO CONSTRUIR ARQUIVOS DE AJUDA W.C. RODRIGUES

ERRORLOG Especifica o nome do arquivo de erro e/ou comentrios gerados aps a compilao do arquivo de ajuda. (mximo 8 caracteres no nome, ex.: ERRORLOG=errajuda.txt ou ERRORLOG=errajuda.err). CONTENTS Especifica o tpico inicial do arquivo de ajuda, em geral o tpico da primeira pgina do arquivo de rtf. (mximo 255 caracteres). CONTENTS=cntAjuda. COMPRESS Especifica como o arquivo de Ajuda deve est comprimido. Os valores so 0 (Nenhuma compresso), 1 (Compresso alta), FALSE (Nenhuma compresso), HIGH (Compresso alta), MEDIUM (Compresso mdia), NO (Nenhuma compresso), TRUE (Compresso alta), YES (Compresso alta). OLDKEYPHRASE Especifica se o compilador deve usar a tabela de frase de chave existente ou criar uma nova durante a compilao, ou seja, arquivos com extenso .ph. Os valores so: 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 ttulo do arquivo de ajuda, que ser exibido na tela do ndice e localizar. (mximo de 255 caracteres). COPYRIGHT Exibe na tela de verso a descrio de direitos autorais do arquivo de ajuda (ex.: Copyright 2000, Lizaro Soft). (mximo 50 caracteres). WARNING o nvel de advertncia que dever ser exibida durante a compilaco. Os valores vo de 13, onde 1 (Relata somente os erros mais severos), 2 (Relata um nmero intermedirio de erros) e 3 (Relata todos os erros e advertncias). REPORT Controla a exibio de mensagens durante o processo de construo. Valores ON e no inserir a opo. Existem outras opes, mas no sero abordadas neste exemplo. 1.1.1.2 Seo WINDOWS Nesta seo esto contidas as informaes, da janela do arquivo de ajuda. Para a janela principal d-se o nome MAIN e para a janela secundria em geral d-se o nome HOWTO, mas o programador poder escolher outro nome para est janela. Abaixo segue as especificaes de uma janela e dois exemplos. NOMEJANELA= "Titulo da janela da ajuda (mximo 255 caracteres)", (X,Y,largura,altura), sizing, (cor da rea do texto), (cor da rea do cabealho). X= Distncia em pixels da janela a esquerda da tela (1024); Y= Distncia em pixels da janela do alto da tela (1024); Sizing= 0 (Configurar a janela para o tamanho especificado pelo x, y, largura, e parmetros de altura) ou 1 (Maximize a janela; ignorando o x, y, largura, e parmetros de altura). Cor da rea do texto= a cor do fundo da rea do texto, segue o padro RGB; Cor da rea do cabealho= a cor do fundo da rea do cabealho. [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, posio e a cor da rea do texto de acordo com as especificaes do sistema, somente a cor do cabealho especificada amarelo claro. (Figura 10) HowTo="Passo-a-Passo", (200,200,500,500),0, (255,255,210), (255,128,0) O exemplo acima janela secundria ter o ttulo "Passo-a-Passo" a disposio 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 parmetros de especificao, X,Y, largura e altura, as cores so amarelo bem claro para rea do texto e laranja para o cabealho. (Figura 11)

COMO CONSTRUIR ARQUIVOS DE AJUDA W.C. RODRIGUES

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 Seo FILES Nesta seo o programador ir listar todos os arquivos de tpicos utilizados para compor o arquivo de ajuda. Podero ser utilizados quantos arquivos o programador achar necessrio, mas ateno quanto maior o nmero de arquivo maior ser dificuldade para atualiz-lo. Quando os arquivo forem salvos devero Ter no mximo 8 carascters (padro DOS), pois j que o compilador roda em DOS, as configuraes deste sistema operacional devero ser respeitadas. O exemplo seguinte especifica dois arquivos de tpico: [FILES] HelperSE.rtf hlpPopUp.rtf 1.1.1.4 Seo CONFIG A seo [CONFIG] contm um ou mais macros que executam aes, como habilitando botes de navegao e registrando funes de bibliotecas de vnculo dinmico (DLL's) (dynamiclink library). Ajuda do Windows executa as macros quando arquivo de Ajuda aberto. Por exemplo, para habilitar os botes de navegao (>> e <<) de um arquivo de ajuda basta inserir o seguinte exemplo: [CONFIG] BrowseButtons()

COMO CONSTRUIR ARQUIVOS DE AJUDA W.C. RODRIGUES

1.1.1.5 Seo MAP A seo [MAP] associa strings de contexto (ou nomes alternativos, aliases) com nmeros de contexto para Ajuda sensvel a contexto. O nmero de contexto corresponde para um valor o aplicativo de "pai" passa para Ajuda do Windows a fim de exibir um tpico particular. Esta seo opcional. A Sintaxe : Contexto-string Nmero de contexto onde: Contexto-string Especifica a string de contexto de um tpico no arquivo de Ajuda. A string pode ser qualquer combinao de caracteres, exceto espaos, e devem ser tambm especificados em um contexto-string Nota de rodap declarao em algum tpico no arquivo de Ajuda. Nmero de contexto Especifica o nmero de contexto para associar com a string de contexto. O nmero pode estar em um ou outro decimal ou C normal formato hexadecimal. S um nmero de contexto pode ser designado para uma string de contexto ou nome alternativo (alias). Designando o mesmo nmero para mais de uma string de contexto gera um erro de compilao. Pelo menos um espao deve separar o nmero de contexto da string de contexto, recomenda-se uma tabulao do teclado (tecla TAB). 1.1.2 Arquivo de Texto (Arquivo de Tpicos) 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 so demostradas na Tabela 8 abaixo: Tabela 1. Caracteres especiais, atribuio e descrio, para a construo do arquivo texto (tpicos) da ajuda. Atribuio2 # (Cerquilha) $ (Sifro) K (letra K maiscula) + (sinal de mais) Duplo subilinhado Sublinhado simples Texto oculto Descrio3 Especifica a string do contexto, ou seja, o identificador do tpico, que ser utilizado pela ajuda para referencia-lo. Mximo de 255 caracteres podendo utilizar letras de A at Z, algarismos, um ponto e um sublinhado. Especifica o ttulo do tpico. Mximo de 127 caracteres, podendo ser utilizado qualquer caractere. Especifica as palavras chaves que sero exibidas no ndice da ajuda. As palavras-chave so opcionais, podendo ser utilizada quantas palavras quiser por tpico, separando-as por ponto e vrgula(;) e coom limite mximo de 255 caracteres Especifica a seqncia de pesquisa e a ordem de navegao dos botes >> e <<. Especifica um link (salto). Quando o texto e clicado o mecanismo da d o salto para o tpico especificado. Exibe numa janela Pop-Up um tpico especificado pelo texto oculto. Referencia o tpico que o texto sublinhado dever saltar. Deve ser especificado logo aps a(s) palavra(s) sublinhada(s) (duplo ou simples) e com um espao antes do pargrafo, para no ocultar o pargrafo 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.

Os caracteres especiais #,$,K e +, so utilizado como nota de rodap, os demais devero ser utilizado no decorrer do texto. 3 Especificao do tamanho mximo de caracteres so para os compiladores HC31 e HC35

COMO CONSTRUIR ARQUIVOS DE AJUDA W.C. RODRIGUES

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, so eles # string do contexto do tpico; $ ttulo do tpico e K Palavras-chave. Aps o planejamento de um pequeno exemplo de um arquivo tpicos 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 tambm a Figura 12 e 13.

Figura 5. Telas do Word 97 e do StarWriter 5.1 (respectivamente)para insero de notas de rodap com caracteres especiais (personalizados). No edite os arquivos criados no Word, no WordPad, pois este no possui ferramentas para criar notas de rodap. Para comear um novo tpico basta inserir um quebra de pgina. Proceda da seguinte forma no Word acesse o menu Inserir>Quebra..., na tela selecione Quebra de Pgina 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

Figura 6. Telas do Word 97 e do StarWriter 5.1, para inserir quebra de pgina (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 usurio 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. Pargrafo 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 pargrafo, existe um espao, que recomendado. Para somente abrir uma janela como Pop-Up, somente sublinhe simples a palavra que ativar a janela. No caso de querer o tpico numa a janela alternativa (Passo-a-Passo), basta aps do nome do tpico (#), inserir palavra com duplo sublinhado>nome da janela, esta dever est especificada no projeto da ajuda, com mostra o Seo WINDOWS. Veja a Figura 17.

Figura 8. Sintaxe para que o mecanismo da ajuda abra o tpico especificado (OQReg), numa janela secundria. 1.1.2.2 Abrindo o Browser padro e o Editor de Correio Eletrnico padro possvel abrir estes dos aplicativo atravs de um arquivo de ajuda, as sintaxe esto nas Figura 18 e 19 abaixo. A(s) palavra(s) que iro acessar os aplicativo podero esta sublinhada com sublinhado simples o duplo.

Figura 9. Sintaxe para abrir o Browser atravs do arquivo de ajuda.

Figura 10. Sintaxe para abrir o Editor de Correio Eletrnico atravs do arquivo de ajuda. 1.1.2.3 Inserindo figuras no arquivo de ajuda As imagens quando bem elaboradas, e trabalhadas, do um belo aspecto ao arquivo de ajuda. O HC31 e HC35, no suportam que as imagens sejam diretamente inseridas no arquivo de

COMO CONSTRUIR ARQUIVOS DE AJUDA W.C. RODRIGUES

texto (tpicos), porm a HCW, j suporta. Outro detalhe que as imagens no podero tem o tamanho acima de 60 KB pois geram um erro de falta de memria na compilao 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 compilao do arquivo de ajuda, geralmente quando a imagem tem um tamanho muito grande (acima de 60KB). As Strings mais utilizadas para referenciar imagens so as seguintes: {bmc} = Ajusta a imagem no centro; {bml} = Ajusta a imagem esquerda; {bmr} = Ajusta a imagem direita; As imagens podero ser do tipo Bitmap Windows (BMP), Windows Metafile (WMF) ou ainda compiladas Hypergraphic Bitmap (SHG), que podero ser criadas atravs do Microsoft HotSpot. Ateno: Como o compilador HC31 e HC35, so executados no DOS os nomes dos arquivos devem ter no mximo oito letras (8), sem contar a extenso, servindo tambm para os diretrios dos projetos a serem criados. 1.1.2.4 Outros formatos suportados pelos compiladores HC31 e HC35 Podero ser inseridas tabelas de formatao simples; Texto com cores diferenciadas; Texto com alinhamento a esquerda, ao centro e a direita; 1.1.2.5 Compilando todos os arquivos Aps 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 usurio acesse-a. Para compilar os arquivo o programa dor tem trs alternativas: utilizando HC 31 ou HC35 a partir do DOS (Figura 21), atravs de um programa editor e compilador como Lizaro Helper Compiler v1.0 (Figura 22) e atravs do Microsoft Help Workshop (Figura 23)

Figura 12. Tela do DOS com a sintaxe para compilao de um projeto de ajuda utilizando os compiladores HC31 ou HC35.

COMO CONSTRUIR ARQUIVOS DE AJUDA W.C. RODRIGUES

Figura 13. Tela de compilao do Lizaro Helper Compiler v1.0 Professional Editon.

Figura 14. Tela de compilao 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 atravs 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 especificaes dos comandos utilizados pelo controle CommomDialog Constante cdlHelpContext cdlHelpQuit cdlHelpIndex cdlHelpContents Valor &H1 &H2 &H3 &H3 Descrio Exibe a ajuda de um tpico em particular Notifica o aplicativo de Ajuda que o arquivo de Ajuda especificada no est mais em uso Exibe o ndice do arquivo de Ajuda especificada Exibe o tpico de contedo no corrente arquivo Ajuda

COMO CONSTRUIR ARQUIVOS DE AJUDA W.C. RODRIGUES cdlHelpHelpOnHelp cdlHelpSetIndex cdlHelpSetContents cdlHelpContextPopup cdlHelpForceFile cdlHelpKey cdlHelpCommandHelp cdlHelpPartialKey &H4 &H5 &H5 &H8 &H9 &H101 &H102 &H105

Exibe a ajuda de como usar a ajuda Fixa o ndice atual para Ajuda de ndice mltiplo Designa um tpico especfico como o tpico de contedo Exibe um tpico identificado por um nmero de contexto Cria um arquivo de Ajuda que exibe texto em uma s fonte Displays Help for a particular keyword Exibe a Ajuda para um comando particular Chama a mecanismo de procura na Ajuda do Windows

1.1.2.7 Executando Arquivo de Ajuda Atravs de API no Visual Basic Para abrir arquivos de ajuda de praxe que utilizemos o conhecido controle ActiveX Commom Dialog, porm se voc no quiser utiliza-lo, basta inserir a seguinte API num mdulo. 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 tpico de ajuda pelo Nmero 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 cdigo 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 tpico especfico, 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 End Sub

10

No evento de um boto ou no menu que queira exibir um tpico especfico, insira as seguintes linhas: Private Sub cmdAjuda_Click() Ajuda_Topico me, nmero 'Onde o nmero referencia o tpico a ser exibido, Seo MAP End Sub