Como Construir Ajuda

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: [email protected]
COMO CONSTRUIR ARQUIVOS DE AJUDA – W.C. RODRIGUES
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:
9 Arquivo de projeto da Ajuda – Arquivo com extensão HPJ;
9 Arquivo de contexto da Ajuda – Arquivo com extensão CNT;
9 Arquivo de Texto da Ajuda, contento os tópicos – Arquivo com extensão RTF;
9 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) (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()
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
# (Cerquilha)
$ (Sifrão)
K (letra K maiúscula)
+ (sinal de mais)
Duplo subilinhado
Sublinhado simples
Texto oculto
Descrição3
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.
Especifica o título do tópico. Máximo de 127 caracteres, podendo ser
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
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
>> e <<.
Especifica um link (salto). Quando o texto e clicado o mecanismo da dá o
salto para o tópico especificado.
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
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
9 Poderão ser inseridas tabelas de formatação simples;
9 Texto com cores diferenciadas;
9 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
cdlHelpContext
Valor
&H1
cdlHelpQuit
&H2
cdlHelpIndex
cdlHelpContents
&H3
&H3
Descrição
Exibe a ajuda de um tópico em particular
Notifica o aplicativo de Ajuda que o arquivo de Ajuda
especificada não está mais em uso
Exibe o índice do arquivo de Ajuda especificada
Exibe o tópico de conteúdo 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
9
Exibe a ajuda de como usar a ajuda
Fixa o índice atual para Ajuda de índice múltiplo
Designa um tópico específico como o tópico de conteúdo
Exibe um tópico identificado por um número 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 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