JavaHelp Základní popis systému JavaHelp Soucástí vetšiny

JavaHelp Základní popis systému JavaHelp Soucástí vetšiny

JavaHelp
Základní popis systému JavaHelp
Soucástí vetšiny interaktivních aplikací je nápoveda (help) – aplikace v Jave nejsou výjimkou.
Systém JavaHelp je napsaný v Jave a je urcený pro aplikace vytvárené v Jave. JavaHelp
poskytuje vývojárum a autorum standardní, plnohodnotný a snadno použitelný systém pro
prezentování on-line informací uživatelum aplikací napsaných v Jave. Tento systém je standardním rozšírením Java SDK a je zdarma k dispozici na http://java.sun.com/.
JavaHelp systém umožnuje vývojárum zprístupnit nápovedu:
• v aplikacích,
• v JavaBeans,
• v appletech.
Obrázek 6.14: Prohlížec nápovedy
Systém JavaHelp má následujících základní rysy:
• prohlížec nápovedy (help viewer) se pripojuje k aplikaci jako jar soubor. Na obrázku 6.14
je ukázka okna s nápovedou.
Prohlížec obsahuje dva panely: jeden pro zobrazení vlastní nápovedy formátované pomocí
HTML 3.2 a druhý panel s navigacním oknem, ve kterém se lze prepínat mezi tremi
záložkami (navigátory):
• obsah (Table of Contents),
•
•
•
•
• rejstrík (Index)
• fulltextové vyhledávání (fulltext search)
Autor nápovedy muže pridávat další navigátory, poprípade muže navigátory ubírat.
Okno prohlížece muže být bud samostatné (panel v pojmech AWT a SWINGu), nebo
muže být soucástí okna aplikace.
Je obvyklé uložit veškeré informace nápovedy do jednoho jar archivu. Vývojári a autori
nápovedy obvykle využívají z duvodu flexibility možnost mít samostatné soubory.
JavaHelp podporuje kontextove závislou nápovedu, existuje vetší množství zpusobu, jak
nápovedu z aplikace vyvolat.
JavaHelp je napsaný v Jave a umožnuje vývojárum vytváret si vlastní vzhled i upravovat
funkcnost.
JavaHelp je navržen pro použití v ruzných typech aplikací i v ruznorodém sítovém prostredí.
• Samostatné aplikace obvykle mají soubor/soubory s nápovedou k dispozici na lokálním
disku a zobrazují ji v samostatném okne viz obrázek 6.15..
• Další možností je umístit soubory s vlastní nápovedou na síti a ne na lokálním disku.
Základní schéma této situace je na obrázku 6.16.
• JavaHelp podporuje vytvárení i tzv. help serveru – tento server podporuje nápovedu pro
více aplikací, umí prohledávat jednotlivé nápovedy (tj. hledání neprobíhá na stanici, ale na
serveru), umí spojovat více nápoved do jedné (duležité v prípade JavaBeans).
• Aplikace pro zobrazení nápovedy nemusí vždy vytváret zvláštní okno – je možno zaclenit
nápovedu prímo do okna aplikace viz obrázek 6.17:
Obrázek 6.15: Možnosti nápovedy, varianta nápoveda v samostatném okne, soubor na
disku.
Obrázek 6.16: Možnosti nápovedy, varianta nápoveda v samostatném okne, soubor na
síti.
Obrázek 6.17: Možnosti nápovedy, varianta nápoveda v okne aplikace, soubor na disku.
Obdobne jako v prípade aplikací je možné využít JavaHelp i v appletech a v JavaBeans.
Vytvárení nápovedy (vytvárení obsahu)
Tato kapitola obsahuje základní informace pro tvorbu souboru s nápovedou. Jednotlivá témata
nápovedy jsou popsána v samostatných HTML souborech dle standardu HTML 3.2. Dále se
vytvárejí speciální soubory s metadaty, které slouží pro prezentaci nápovedy (napr. soubor
s obsahem, soubor s indexem, soubory pro vyhledávání). Celek se oznacuje pojmem helpset.
Pro tvorbu nápovedy se casto používá speciální programové vybavení (na http://java.sun.com/
je k dispozici seznam techto programu od nezávislých výrobcu), které mnohé detaily tvorby
nápovedy autorum odstíní.
Zde si popíšeme základní postup pro vytvárení nápovedy. Mnohé podrobnosti a speciality
vynecháme – pokud budete vytváret vlastní nápovedu, doporucujeme prostudovat
dokumentaci k systému JavaHelp, kterou si stáhnete z java.sun.com soucasne s produktem..
Vytvorení nápovedy se skládá z následujících kroku:
• vytvorení souboru s jednotlivými tématy (texty a obrázky),
• vytvorení souboru popisujícího HelpSet
• vytvorení souboru s mapou odkazu,
• vytvorení souboru s obsahem,
• vytvorení souboru s indexem,
• vytvorení databáze pro fulltextové vyhledávání,
• kompletace všech cástí do JAR souboru.
Soucástí distribuce je pomocný program hsviewer, kterým si lze vytvárenou nápovedu
prohlížet – tj. pri vytvárení obsahu nápovedy není potreba mít k dispozici celou aplikaci.
Vytvárení souboru s jednotlivými tématy
Pro každé téma musí existovat samostatný soubor ve formátu HTML dle standardu HTML
3.2 (tj. nelze používat nekterá rozšírení z poslední doby). Soucástí mohou být i obrázky. Mezi
jednotlivými tématy je možno si vytváret vlastní odkazy (pomocí <A HREF=...>), je nutné
však používat relativní cesty. HTML soubory s tématy se obvykle umístují do samostatného
podadresáre, pri vetším rozsahu nápovedy je vhodné ji rozdelit napr. dle skupin témat do
jednotlivých podadresáru.
V HTML kódu lze používat speciální rozšírení pres definici speciálních objektu v HTML
kódu - napr. lze takto používat popup okna Konkrétní popis této techniky vcetne príkladu je
k dispozici v dokumentaci. Lze též definovat vlastní rozšírení.
Vytvorení souboru popisujícího HelpSet
V korenovém adresári s nápovedou musí existovat soubor s koncovkou .hs, který obsahuje
základní informace o nápovede. Jméno tohoto souboru udává jméno této nápovedy (jméno
helpsetu). Soubor je ve formátu XML (soucástí distribuce javahelpu je i príslušný DTD
soubor). Následuje príklad jednoduchého souboru s popisem helpsetu:
<?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>Cestovni Kancelar</title>
<maps>
<homeID>Cestovni_kancelar</homeID>
<mapref location="cestovka.jhm" />
</maps>
<view>
<name>Obsah</name>
<label>Obsah napovedy</label>
<type>javax.help.TOCView</type>
<data>cestovkaTOC.xml</data>
</view>
<view>
<name>Index</name>
<label>Index k napovede</label>
<type>javax.help.IndexView</type>
<data>cestovkaIndex.xml</data>
</view>
<view>
<name>Search</name>
<label>Search</label>
<type>javax.help.SearchView</type>
<data engine="com.sun.java.help.search.DefaultSearchEngine">
JavaHelpSearch
</data>
</view>
</helpset>
Soubor helpset obsahuje následující základní tagy:
<helpset>
definuje helpset, obsahuje následující tagy:
<title>
nadpis helpsetu,
<maps>
urcení souboru s mapou odkazu, obsahuje následující tagy:
<homeID> odkaz, který se použije, pokud není z aplikace urceno, který se
má zobrazit,
<mapref>
odkaz na jméno souboru (url) s mapou odkazu,
<view>
definuje jednotlivé navigátory použité pri zobrazení helpsetu,, tento tag
se muže opakovat,
<name>
jméno navigátoru,
<label>
krátké jméno navigátoru, použije se pri zobrazení (napr. Obsah,
Index, ...)
<type>
typ pohledu, v podstate je to jméno trídy, která se použije pro
zobrazení navigátoru,
<data>
jméno souboru (url), který obsahuje data pro tento navigátor
(napr. url souboru s obsahem),
Vytvorení souboru s mapou
Soubor s mapou obsahuje prirazení mezi identifikací jednotlivých témat nápovedy
v programu a URL príslušných HTML souboru, tj. v programu se nepoužívají jména
jednotlivých HTML souboru. Toto umožnuje vetší flexibilitu pri vytvárení nápovedy a také
napr. vytvárení vícejazycných verzí nápovedy. Jména odkazu se používají v souborech
s definicí obsahu, v souborech s definicí indexu a pri používání kontextove závislé nápovedy
v programu. Soubor s mapou by mel obsahovat i odkazy na obrázky.
Soubor s mapou odkazu používá formát XML. Následuje jednoduchý príklad souboru
s mapou odkazu:
<?xml version='1.0' encoding='ISO-8859-1' ?>
<!DOCTYPE map
PUBLIC
"-//Sun Microsystems Inc.//DTD JavaHelp Map Version 1.0//EN"
"http://java.sun.com/products/javahelp/map_1_0.dtd">
<map version="1.0">
<mapID target="Cestovni_kancelar"
url="HTML/Cestovni_kancelar.htm"/>
<mapID target="Novy_zakaznik"
url="HTML/Novy_zakaznik.htm"/>
<mapID target="Seznam_zakazniku"
url="HTML/Seznam_zakazniku.htm"/>
</map>
V souboru se používají dva tagy:
<map> definuje mapu, obsahuje <mapID> tagy,
<mapID>
definuje jednotlivé odkazy, má dva atributy:
target definuje jméno odkazu,
url
specifikuje url, na které se odkaz odkazuje,
Vytvorení souboru s obsahem
Soubor s obsahem obsahuje potrebné údaje pro navigátor TOC (Table of Contents) –
javax.helpset.TOCView. Tento soubor používá opet formát XML. Následuje jednoduchý
príklad souboru s obsahem:
<?xml version='1.0' encoding='windows-1250' ?>
<!DOCTYPE toc
PUBLIC
"-//Sun Microsystems Inc.//DTD JavaHelp TOC Version 1.0//EN"
"http://java.sun.com/products/javahelp/toc_1_0.dtd">
<toc version="1.0">
<tocitem text="Cestovní kancelár" target="Cestovni_kancelar"/>
<tocitem text="Seznam zákazníku" target="Seznam_zakazniku">
<tocitem text="Nový zákazník" target="Novy_zakaznik"/>
</tocitem>
</toc>
Obrázek 6.18: Vzhled obsahu nápovedy.
V souboru s obsahem se používají následující tagy:
<toc> definuje obsah, obsahuje tagy <tocitem>,
<tocitem>
definuje jednotlivé položky obsahu, tyto tagy mohou být vnoreny do
sebe – tím se vytvorí hierarchická struktura. Tento tag má tyto atributy:
text
urcuje text zobrazený v obsahu,
target (volitelný)
obsahuje jméno odkazu ze souboru mapy odkazu, který
se zobrazí pri zvolení tohoto nadpisu,
image (volitelný)
obsahuje jméno odkazu na obrázek ze souboru mapy
odkazu. Tento obrázek ve formátu JPEG nebo GIF se zobrazí
v obsahu.
Vytvorení souboru s indexem
Soubor s indexem obsahuje potrebné údaje pro navigátor Index (javax.helpset.IndexView).
Tento soubor používá opet formát XML. Následuje jednoduchý príklad souboru s indexem:
<?xml version='1.0' encoding='windows-1250' ?>
<!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="Konec" target="Cestovni_kancelar" />
<indexitem text="Help" target="Cestovni_kancelar" />
<indexitem text="Seznam zákazníku" target="Seznam_zakazniku" />
<indexitem text="Zobraz detail" target="Seznam_zakazniku" />
<indexitem text="Nový zákazník" target="Novy_zakaznik" />
<indexitem text="Jméno zákazníka" target="Novy_zakaznik" />
<indexitem text="Príjmení" target="Novy_zakaznik" />
<indexitem text="Rodné císlo" target="Novy_zakaznik" />
<indexitem text="Císlo pasu" target="Novy_zakaznik" />
<indexitem text="Adresa" target="Novy_zakaznik">
<indexitem text="Typ adresy" target="Novy_zakaznik" />
<indexitem text="Ulice" target="Novy_zakaznik" />
<indexitem text="Císlo popisné" target="Novy_zakaznik" />
<indexitem text="Mesto" target="Novy_zakaznik" />
<indexitem text="PSC" target="Novy_zakaznik" />
<indexitem text="Stát" target="Novy_zakaznik" />
</indexitem>
</index>
Obrázek 6.19: Vzhled navigátoru Index.
V souboru s indexem se používají následující tagy:
<index>
definuje index, obsahuje tagy <indexitem>,
<indexitem> urcuje jednotlivé položky indexu, tyto tagy mohou být vnoreny do sebe
– tím se vytvorí hierarchická struktura. Tento tag má následující atributy:
text
urcuje text zobraze ný v indexu,
target (volitelný)
obsahuje jméno odkazu ze souboru mapy odkazu, který
se zobrazí pri zvolení této položky indexu uživatelem,
Vytvorení databáze pro fulltextové vyhledávání
Systém pro fulltextové vyhledávání v javahelpu umožnuje nejen vyhledat príslušná témata
odpovídající dotazu, ale snaží se je též ohodnotit a seradit z hlediska relevantnosti. Pro
zprístupnení fulltextového vyhledávání je potreba v definici helpsetu uvést navigátor
javax.javahelp.SearchView a vytvorit databázi pro fulltextové vyhledávání. Tato databáze má
speciální strukturu a je možno ji vytvorit/aktualizovat pomocí programu jhindexer, který je
soucástí distribuce javahelpu. Program jhindexer spustte v adresári se souborem popisujícím
helpset a jako parametr mu zadejte jména podadresáru, které chcete indexovat. Program
jhindexer poté vytvorí speciální podadresár JavaHelpSearch s potrebnými soubory pro
navigátor.
Obrázek 6.20: Vzhled navigátoru Search.
Kompletace všech cástí do JAR souboru
Vytvorenou nápovedu je obvyklé distribuovat v jednom jar souboru, který lze vytvorit
programem jar. Popis tohoto programu je uveden v [JavaDoc] popr. v [UvodJava].
Použití JavaHelpu v programech
Trídy potrebné pro používání JavaHelpu jsou v souboru jh.jar z distribuce JavaHelpu. Pri
prekladu i pri spouštení musí být tento jar soubor uveden v CLASSPATH, aby se našli
potrebné trídy.
Pridání nápovedy do programu
Pridání nápovedy do programu volané pres nabídku v menu se skládá ze ctyr kroku.
1. Velmi vhodné je doplnit do zdrojového textu import klauzuli pro balícek javax.help:
import javax.help.*;
Dále je vhodné použít import klauzuli pro trídu java.net.URL:
import java.net.URL;
Jako promenné objektu je dále potreba nadeklarovat dve promenné, první typu HelpSet a
druhou typu HelpBroker, napr. takto:
HelpSet hs;
HelpBroker hb;
2. Prvním programovým krokem je udání cesty (popr. vyhledání) souboru popisujícího
helpset a vytvorení instance trídy HelpSet. Nejjednodušší je následující zpusob:
try {
URL hsURL = HelpSet.findHelpSet (null, "help/cestovka.hs");
hs = new HelpSet (null, hsURL);
}
catch (Exception ee) {
System.out.println("HelpSet cestovka.hs nenalezen");
return;
}
Následující varianta kódu vyhledává soubor s popisem helpsetu v rámci CLASSPATH:
try {
ClassLoader cl = CestovniKancelar.class.getClassLoader();
URL url = HelpSet.findHelpSet(cl, "cestovka");
mainHS = new HelpSet(cl, url);
}
catch (Exception ee) {
System.out.println ("HelpSet cestovka.hs nenalezen");
}
catch (ExceptionInInitializerError ex) {
System.err.println("initialization error:");
ex.getException().printStackTrace();
};
3. Dále by melo následovat vytvorení instance trídy HelpBroker, která zajištuje zobrazování
nápovedy:
hb = hs.createHelpBroker();
4. Následuje kód, který pridá do menu položku pro vyvolání nápovedy
JMenu help = new JMenu("Help");
menuBar.add(help);
JMenuItem menu_help = new JMenuItem("Nápoveda k programu");
menu_help.addActionListener (new CSH.DisplayHelpFromSource(hb));
Následující kód vytvorí tlacítko a priradí mu akci pro vyvolání nápovedy:
JButton helpbutton = new JButton("Help");
helpbutton.addActionListener(new CSH.DisplayHelpFromSource(mainHB));
Kontextove závislá nápoveda
Pri vytvárení kontextove závislé nápovedy musí programátor vyrešit dva problémy – musí
urcit zpusob, jak vyvolat tuto nápovedu (obvyklé je pomocí klávesy F1) a dále musí urcit,
které téma nápovedy se má zobrazit v príslušné situaci. Systém javahelp poskytuje více
variant rešení pro rešení obou problému. V následujícím textu si ukážeme základní varianty.
Prirazení kontextové nápovedy zajištuje objekt HelpBroker pomocí metody enableHelpKey,
která má tri parametry:
- AWT komponenta, pro kterou se prirazuje klávesa F1, obvykle se zde zadává Frame
(JFrame) nebo Panel (JPanel),
- identifikátor nápovedy (viz soubor s mapou), která se standardne zobrazí pri stisku F1,
toto prirazení lze prepsat u vložených objektu,
- helpset, který se má použít – obvykle se uvádí hodnota null, která znamená, že se použije
helpset prirazený pri vytvárení objektu HelpBroker,
V konstruktoru objektu ObrZakaznikVstup by kód mohl vypadat následovne:
CestovniKancelar.mainHB.enableHelpKey(this, "Novy_zakaznik", null);
K jednotlivým vstupním polím v rámci této obrazovky mužeme priradit téma kontextové
nápovedy pomocí statické metody CSH.setHelpIDString se dvemi parametry:
- komponenta, ke které se má priradit nápoveda (napr. typu JTextField),
- identifikátor nápovedy (viz soubor s mapou).
Napr. ke vstupnímu poli jmenoVstup lze priradit nápovedu následujícím príkazem:
CSH.setHelpIDString(jmenoVstup, "Novy_zakaznik.jmeno");
Statická metoda CSH.setHelpIDString neaktivuje klávesu F1, tj. u panelu ci rámu
obsahujícího príslušnou komponentu musí být prirazena klávesa F1 (aktivován príslušný
ActionListener) pomocí metody enableHelpKey objektu HelpBroker.
Poznámka: Podpora pro jeden typ kontextove závislé nápovedy, tzv. tooltips je soucástí
knihovny SWING.
Lokalizace nápovedy
Systém JavaHelp podporuje lokalizaci jednotlivých cástí nápovedy (a to vcetne vytvárení
vícejazycných nápoved):
• lokalizaci zobrazování nápovedy,
• lokalizaci helpsetu,
• lokalizaci HTML souboru,
• lokalizaci XML dat,
• lokalizaci fulltextového vyhledávání.
Jednotlivé prvky jsou popsány v dokumentaci programového vybavení.