Artigo Java Magazine 35 - JavaHelp na Prática

Esse artigo faz parte da revista Java Magazine edição 35. Clique aqui para ler todos os artigos desta edição

Atenção: por essa edição ser muito antiga não há arquivo PDF para download.Os artigos dessa edição estão disponíveis somente através do formato HTML. 

JavaHelp na Prática

Saiba como incorporar help on-line em suas aplicações Java

Aprenda o padrão Java para criação e visualização de Sistemas de Ajuda, facilitando a vida dos usuários e tornando suas aplicações mais profissionais

À medida que o Java se torna mais popular, as aplicações desenvolvidas ficam cada vez mais profissionais. Nesse cenário, cresce a necessidade de sistemas de ajuda (ou help on-line) completos e fáceis de navegar, que auxiliem o usuário final a entender e utilizar os programas. Esses sistemas também são importantes para reduzir custos com treinamento e suporte. Só como exemplo, imagine o caos que seria se o programa de declaração do Imposto de Renda, usado todo ano por mais de 20 milhões de contribuintes, não tivesse um bom sistema de ajuda on-line.

Esse artigo aborda o JavaHelp, uma solução puramente Java que permite disponibilizar help on-line em aplicações Java. Inicialmente veremos como instalar e usar o JavaHelp, aprendendo como visualizar e navegar em um sistema de ajuda ou help on-line (que chamaremos de "help", para simplificação). Em seguida, veremos como são estruturados os arquivos que compõem um help no padrão JavaHelp. Por fim, aprenderemos como associar o help a uma aplicação desktop bem simples, abrangendo as funcionalidades mais comuns oferecidas pela API do JavaHelp.

Instalação

Para obter o JavaHelp 2.0, faça  o download do arquivo compactado (javahelp-2_0_02.zip, ou uma versão superior) diretamente do site da Sun, em java.sun.com/products/javahelp. Descompacte o arquivo em uma pasta qualquer; é criada uma estrutura de diretórios semelhante à da Figura 1. Depois defina a variável de ambiente JAVAHELP_HOME, apontando para a pasta raiz.

Para usar o JavaHelp 2.0 é necessário no mínimo o JDK 1.2.2 instalado. Além disso, deve ser acrescentado o JAVAHELP_HOME/javahelp/lib/jh.jar ao classpath do sistema operacional[1]. É desejável também adicionar o JAVAHELP_HOME/javahelp/bin à variável de ambiente PATH.

Com isso o JavaHelp está instalado. Para testar se está funcionando corretamente, utilize o comando (em uma linha):

java -jar demos/bin/hsviewer.jar

    -helpset doc/jhug/jhug.hs

(Para simplificar, vamos supor sempre que o diretório corrente é o JAVAHELP_HOME, ou seja, a pasta raiz da instalação do JavaHelp.) Executando o comando anterior, você verá o guia do usuário do JavaHelp, em uma tela similar à exibida na Figura 2. Esse guia também está disponível em PDF, em doc/jhug.pdf.

O hsviewer é um utilitário que permite a visualização de qualquer help no padrão JavaHelp, a partir de seu arquivo de HelpSet (.hs). Para facilitar, você pode incluir no PATH do sistema operacional o JAVAHELP_HOME/demos/bin, e desta forma executar diretamente o comando java –jar hsviewer.jar –helpset . Se você não informar o parâmetro –helpset, o utilitário apresentará uma tela onde se pode escolher o help diretamente no sistema de arquivos (veja a Figura 3).

Visualização e navegação

A visualização de sistemas de ajuda criados com o JavaHelp não é muito diferente do que estamos acostumados a ver em outros padrões como o WinHelp ou OracleHelp. Como podemos observar na Figura 2, a janela é dividida em quatro partes principais, descritas brevemente em seguida (termos em inglês são apresentados para facilitar a obtenção de informações adicionais na documentação):

1.     Barra de Menu (Menu Bar) – O menu File apresenta opções para abrir arquivos na área de conteúdo ou para fechar a janela. No menu Options é possível escolher o tipo e o tamanho da fonte utilizado nos outros painéis. Normalmente a barra de menus não é exibida quando o help é acionado por uma aplicação específica (e não pelo hsviewer).

2.     Barra de Ferramentas (Toolbar) – Contém botões para Página Anterior (Previous Page), Próxima Página (Next Page), Imprimir (Print), Configurar Página (Print Setup) e Adicionar a Favoritos (Add to Favorites), nesta ordem.

3.     Painel de Navegação (Navigation Pane) – Exibe os tópicos de ajuda: TOC (Table Of Contents), em uma classificação hierárquica; Índice (Index), por ordem alfabética; Favoritos (Favorites), que permite guardar referências para acesso posterior; e Pesquisa (Search), possibilitando efetuar buscas por palavras-chave.

4.     Painel de Conteúdo (Content Pane) – Área onde é exibido o conteúdo correspondente ao tópico selecionado no Painel de Navegação.

Além da visualização padrão (chamada de Main Window, ou Janela Principal) que acabamos de ver, existem mais dois outros tipos de janelas que podem ser usadas para exibição de tópicos do help. A Janela Secundária (Secondary Window), por padrão, pode ser redimensionada e apresenta apenas o Painel de Conteúdo (mas é possível configurá-la para exibir outras áreas). Já uma janela do tipo Popup (Popup Window) contém apenas um painel de conteúdo e não é redimensionável, ficando aberta até que qualquer ponto fora da janela seja clicado. Nossos exemplos utilizarão a Janela Principal e janelas Popup, que são as mais comuns.

Entendida a forma de apresentação do JavaHelp, estamos prontos para compreender o formato dos arquivos internos de um help.

Criação de um help

Um help no padrão JavaHelp é composto por um conjunto de três tipos de arquivos, que juntos constituem um HelpSet.

·         Arquivos de dados (data files) – São dois arquivos em XML: o arquivo de HelpSet (.hs) propriamente dito, que é o arquivo de controle para todo o help, e o arquivo de mapeamento (comumente map.xml) utilizado para associar um identificador (ID) a cada tópico do help.

·         Arquivos de navegação (navigation files) – São também arquivos XML que definem os tópicos exibidos do Painel de Navegação: TOC (Table of Contents), Índice (Index), Pesquisa (Search), Glossário (Glossary) e Favoritos (Favorites).

·         Arquivos de tópicos (topic files) – Arquivos HTML com o conteúdo do help.

O conteúdo do nosso exemplo de help contempla algumas partes deste próprio artigo. A estrutura de diretórios e todos os arquivos necessários são mostrados na ...