Teléfono y Whatsapp: 675 18 68 80

Manual de JavaHelp

JavaHelp, esa magnífica librería con la que podemos crear ayudas para aplicaciones Java, muy útil tiempos atrás y que ahora está casi obsoleta al no sacar nuevas actualizaciones… Melancolías aparte, JavaHelp sigue resultando muy útil sobretodo cuando nuestra aplicación va destinada a un público no profesional, que pocas veces ha cogido un ordenador y que no sabe por dónde coger nuestra aplicación.

En esta breve entrada voy a explicar cómo descargar, añadir JavaHelp en nuestro proyecto, cómo generar documentación y cómo indexar contenido para el buscador interno de la propia librería.

descargar JavaHelp

Aunque aún no han cerrado la página oficial, es difícil encontrar el enlace de descarga de la misma, así que subo el .jar a mi web y lo podéis descargar desde aquí.
Lo descomprimís, copiáis el jar que hay dentro en la carpeta /lib del proyecto Java y después lo añadimos como librería.

directorios ayuda

Hay que crear unos directorios donde van a estar los ficheros de ayuda, tanto html como índices para cargar con JavaHelp. Para ello mi recomendación personal es incluirlos dentro de la carpeta src, así si nuestro proyecto se encuentra en /src/proyecto, creamos un directorio help y dentro de este otro llamado html, de tal manera que queden así:

/src/proyecto/help
/src/proyect/help/html

ficheros de ayuda

En la carpeta help, creamos los siquientes ficheros:

help.hs
indice.xml
mapa.jhm
tablacontenidos.xml

de tal manera que cada uno de ellos contenga lo siguiente:
help.hs:

<?xml version="1.0" encoding='ISO-8859-1' ?>
<!DOCTYPE helpset PUBLIC "-//Sun Microsystems Inc.//DTD JavaHelp HelpSet Version 1.0//EN" "http://java.sun.com/products/javahelp/helpset_1_0.dtd">
 
<helpset version="1.0">
	<title>Ayuda Generador de Guiones Sociales</title>
	<maps>
		<!-- Pagina por defecto al mostrar la ayuda -->
		<homeID>manual</homeID>
		<!-- Que mapa deseamos -->
		<mapref location="mapa.jhm"/>
	</maps>
 
	<!-- Las Vistas que deseamos mostrar en la ayuda -->
	<view>
		<name>Tabla Contenidos</name>
		<label>Tabla de contenidos</label>
		<type>javax.help.TOCView</type>
		<data>tablacontenidos.xml</data>
	</view>
 
	<view>
		<name>Indice</name>
		<label>El indice</label>
		<type>javax.help.IndexView</type>
		<data>indice.xml</data>
	</view>
 
	<view>
		<name>Buscar</name>
		<label>Buscar</label>
		<type>javax.help.SearchView</type>
		<data engine="com.sun.java.help.search.DefaultSearchEngine">
			JavaHelpSearch
		</data>
	</view>
 
</helpset>

indice.xml:

<?xml version='1.0' encoding='ISO-8859-1'  ?>
<!DOCTYPE index PUBLIC "-//Sun Microsystems Inc.//DTD JavaHelp Index Version 1.0//EN" "http://java.sun.com/products/javahelp/index_1_0.dtd">
<index version="1.0">
        <indexitem text="Manual"    target="manual"/>
        <indexitem text="Instalar"    target="instalar"/>
</index>

mapa.jhm:

<?xml version='1.0' encoding='ISO-8859-1'?>
<!DOCTYPE map
PUBLIC "-//Sun Microsystems Inc.//DTD JavaHelp Map Version 2.0//EN" "http://java.sun.com/products/javahelp/map_2_0.dtd">
<map version="1.0">
   <mapID target="manual" url="html/1-manual.html" />
   <mapID target="instalar" url="html/2-instalar.html" />
</map>

tablacontenidos.xml:

<?xml version="1.0" encoding="ISO-8859-1"?>
<toc version="1.0"> 
	<!--  categoryclosedimage="FolderClosed" categoryopenimage="FolderOpened" topicimage="ItemIco"-->
	<tocitem text="Manual"    target="manual">
		<tocitem text="Instalar"    target="instalar"/>
	</tocitem>
</toc>

y en la carpeta html creamos dos ficheros simples:
1-manual.html:

<html>
<head>
	<title>Manual</title>
</head>
<body>
	<h1>Manual</h1>
</body>
</html>

2-instalar.html:

<html>
<head>
	<title>Instalar</title>
</head>
<body>
	<h1>Instalar</h1>
</body>
</html>

se pueden tener tantos ficheros html como queramos, pero habrá que indicarlos también en los ficheros anteriores o no funcionará.

compilar los índices de ayuda

JavaHelp lleva dentro una pestaña que es un buscador de contenido, pero para que funcione, hay que indexar los ficheros html a un formato propietario ya que la búsqueda se realiza sobre estos indices y no sobre los ficheros. Comentar que cada vez que se modifique algo de cualquier fichero html, habrá que volver a recompilar.

Descargamos todas las librerías de JavaHelp y las descomprimimos por ejemplo en el escritorio.

Ahora vamos a la carpeta donde esté la carpeta help del proyecto:

cd /home/usuario/workspace/proyecto/src/proyecto/help/

y una vez allí, conociendo la ruta de donde hemos extraído las librerías anteriores, ejecutamos el siguiente comando para generar los índices de búsqueda:

java -jar /home/usuario/Escritorio/jh2.0/javahelp/bin/jhindexer.jar html

nos creará una carpeta llamada JavaHelpSearch, ahora ya podemos llamar a nuestra ayuda desde la aplicación.

llamar a javahelp desde código

import javax.help.HelpBroker;
import javax.help.HelpSet;
 
public class Prueba{
 
//Método llamado al cargar la ayuda.
private void cargarAyuda(){
try {
	// Carga el fichero de ayuda
	File fichero = new File("src/com/proyecto/help/help.hs");
	URL hsURL = fichero.toURI().toURL();
 
	// Crea el HelpSet y el HelpBroker
	HelpSet helpset = new HelpSet(getClass().getClassLoader(), hsURL);
	HelpBroker hb = helpset.createHelpBroker();
 
	// Pone ayuda a item de menu al pulsar F1. mntmIndice es el JMenuitem
	hb.enableHelpOnButton(mntmIndice, "manual", helpset);
	hb.enableHelpKey(principal.getContentPane(), "ventana_principal", helpset);
 
} catch (Exception e) {
	logger.error("Error al cargar la ayuda: " + e);
}
}
}

Por último, si queremos que la ayuda esté incluida dentro de un jar (para distribuirlo todo en el mismo paquete), os recomiendo revisar esta otra entrada.

Fuente: Chuidiang.

  • walo

    Muy buenas, hace años que trabajé con JavaHelp, pero creo recordar que era todo muy manual, es decir, creaba todo a mano: mntmIndice y principal .