Hjälpsystem med Java Help

Java Help är ett API för att hantera hjälpsystem. Dess användargränssnitt är hämtat från Swing. Största fördelen över andra hjälpsystem torde vara att det är helt integrerat med övriga Java API och därmed blir mycket flexibelt och (naturligtvis) plattformsoberoende. Det är till exempel lätt att använda över ett nätverk. Det ingår inte i JDK utan är en extension, du kan hämta den på http://java.sun.com/products/javahelp/. I nedladdningen ingår demoprogram och en utomordentlig manual (jh1.1/doc/jhug.pdf). Sidorna 52-112 beskriver steg för steg hur man bygger upp ett hjälpsystem. Den här sidan är en mycket kort sammanfattning av denna del av manualen.

Att skriva ett hjälpsystem

Att skriva ett hjälpsystem blir väsentligt enklare med ett utvecklingsverktyg av något slag. På http://java.sun.com/products/javahelp/industry.html finns en lista över olika verktyg som stöder Java Help. Flera av dem har gratis demoversioner.

Använder du inget av ovanstående verktyg kan du ändå prova ditt hjälpsystem utan att behöva skriva ett program som använder det. Använd då kommandot hsviewer som ingår i Java Help, det står mer om det på sid 53 i ovan nämnda manual.

Här kommer ett exempel på de olika delarna i ett hjälpsystem. Det utgör hjälpen till ett fiktivt ritprogram, Draw-it.

HelpSet

HelpSet-filen talar om var de övriga filerna i hjälpsystemet finns. Maps, TOC, Index och Search pekar ut var och en av nedanstående fyra filer. Här finns HelpSet:et, draw-it.hs.

Map

Map-filen definierar bokmärken i hjälpsystemet, se det här exemplet: draw-it.jhm. Target är namnet på bokmärket och url är adressen som bokmärket representerar.

Innehållsförteckning

Denna fil anger hur innehållsförteckningen ser ut, se draw-itHelpTOC.xml. Text är den text som ska stå i innehållsförteckningen, target är det bokmärke som texten ska peka på.

Index

Denna fil anger hur indexet ser ut, se draw-itHelpIndex.xml. Text är den text som ska stå i indexet, target är det bokmärke som texten ska peka på.

Fritextsökningar

För att användaren ska kunna göra fritextsökningar i hjälpsystemet finns ett verktyg, jhindexer, vilket skapar en databas med länkar till alla ord i hjälpsystemets alla filer. Jhindexer igår i Java Help, läs mer om det på sid 81-83 i manualen. Det enda du behöver göra för att möjliggöra fritextsökningar är att köra jhindexer.

Hjälptexten

Själva hjälptexten skrivs i HTML-filer, inget konstigt med dem. De hjälpfiler som ingår i exemplet kan du hitta i katalogerna draw och files den här katalogstrukturen.

Att visa hjälpsystemet från ett Javaprogram

Det är snarast lättare att visa hjälpsystemet än att skriva det. Programmet DrawIt.java använder ovanstående hjälpsystem (förutom det gör det ingenting).

Raden URL hsURL = HelpSet.findHelpSet(null, "help/draw-it.hs") skapar en URL till HelpSet-filen. Raden hs = new HelpSet(null, hsURL) skapar ett objekt av klassen HelpSet, vilket representerar HelpSet-filen.
HelpBroker hb = hs.createHelpBroker() skapar en HelpBroker, vilken innehåller en del nyttometoder för att visa hjälpsystemet.
hb.enableHelpOnButton( content, "top", null ) lägger till an ActionListener till content, som är det JMenuItem på hjälpmenyn som användaren ska välja för att se hjälpen. Detta är allt som krävs för att hela hjälpsystemet ska startas.
Nedan finns några exempel på hur hjälpsystemet kan styras till att visa hjälp om det som användaren för tillfället håller på med, i stället för att visa hjälpens förstasida. Klassen CSH (förkortning av Context Sensitive Help) innehåller statiska metoder för att hantera detta.

Metoden setHelpIDString() associerar ett bokmärke ur map-filen, se ovan, med en java.awt.Component.
Raden hb.enableHelpKey( getRootPane(), "top", null ) gör att när användaren trycker på knappen F1 kommer det hjälpavsnitt att visas som är associerat, se föregående punkt, med den java.awt.Component som har fokus. Detta gäller endast om Componenten ligger i den JRootPane som skickats till metoden enableHelpHey().
new CSH.DisplayHelpFromSource( hb ) skapar en ActionListener som kommer att visa det hjälpavsnitt som är associerat med den Component som den får ActionEvent från.
new CSH.DisplayHelpAfterTracking( hb ) skapar en ActionListener som kommer att visa det hjälpavsnitt som är associerat med den Component som användaren klickar på.