Obrázek 6.14: Prohlížec nápovedy

Transkript

1 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 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),

2 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 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 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.

3 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.

4 Pro tvorbu nápovedy se casto používá speciální programové vybavení (na 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 '?> <!DOCTYPE helpset PUBLIC "-//Sun Microsystems Inc.//DTD JavaHelp HelpSet Version 1.0//EN" " <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>

5 </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:

6 <?xml version='1.0' encoding='iso '?> <!DOCTYPE map PUBLIC "-//Sun Microsystems Inc.//DTD JavaHelp Map Version 1.0//EN" " <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" " <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:

7 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" " <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>

8 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].

9 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();

10 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,

11 lokalizaci XML dat, lokalizaci fulltextového vyhledávání. Jednotlivé prvky jsou popsány v dokumentaci programového vybavení.