Pomocí nápovědného překladače je možno vytvořit nápovědný soubor (help file) zajišťující on-line nápovědu v aplikacích pod Windows. Tento nápovědný soubor může obsahovat :
* texty různých fontů, barev a velikostí, rozdělené na jednotlivá témata,
* grafické objekty obsahující bitové mapy v různém rozlišení, jež byly vytvořeny v některé aplikaci pod Windows,
* nápovědná makra rozšiřující a automatizující operace nápovědného systému,
* tzv. horké plochy, jež představují senzitivní plochy (při práci s myší). Zajišťují skoky na témata obsahující informace o daném objektu, popřípadě vyskakovací okna s těmito texty.
* sekundární okna pro prezentaci relačních informací.
* klíčová slova zajišťující vyhledávací procesy.
Všechny informace, které budou posléze v procesu tvorby složeny do podoby nápovědného souboru musí být uloženy v jednotlivých zdrojových souborech podle charakteru informací. Jsou to následující typy souborů :
|
Textové soubory |
.RTF |
obsahují text pro nápovědný soubor spolu s návěštími pro skoky a vyhledávání, případně vloženými obrázky ve formátu RTF (Rich Text Format). K vytvoření lze použít např. editor MS-Word. |
|
Projektový soubor |
.HPJ |
obsahuje seznam grafických a textových souborů potřebných k vytvoření nápovědného systému. Dále obsahuje makra, definice okna a důležité záznamy potřebné pro překladač. Musí být napsán v editoru, který nevkládá doplňující znaky, např. : NOTEPAD.EXE. |
|
Soubory s bitovými mapami |
.BMP |
obsahují jednoduchou grafiku ve formátu bitových map. Projektový soubor se může odkazovat na různý počet souborů .BMP. |
|
Meta soubory |
.WMF |
obsahují jednoduchou grafiku v meta souborovém formátu. Např. vytvořenou v CorelDraw. |
|
Hyper grafika |
.SHG |
obsahuje bitové mapy a meta soubory, jež jsou editovány pomoci editoru SHED.EXE, tedy doplněné o horké plochy. |
|
Multiple Resolution soubory bitových map |
.MRB |
obsahují více, než jednu verzi bitových map a metasouborů pro různá rozlišení grafických adaptérů, jež jsou přeloženy do jednoho souboru. |
Kromě souborů .RTF a .HPJ jsou ostatní soubory pro vytvoření nápovědného systému nepovinné.
K tvorbě jednotlivých typů souborů slouží následující nástroje :
|
Nápovědný překladač |
zajišťuje překlad textových a grafických souborů, které jsou specifikovány v projektovém souboru. |
|
Editor horkých ploch |
otevírá bitové mapy a metasoubory pro definici horkých ploch v grafice. |
|
Multiple Resolution Bitmap Compiler MRBC.EXE |
kompiluje bitové mapy různých obrazovkových rozlišení do jednoho souboru. |
Na obr. 2 je znázorněna návaznost jednotlivých souborů a nástrojů pro jejich zpracování při tvorbě nápovědného souboru.
Obr. 2. Návaznost jednotlivých částí nápovědného souboru
Při tvorbě nápovědných souborů je vhodné si rozdělit práci do několika ucelených a relativně uzavřených částí, které na sebe navazují :
1) Naplánování nápovědného souboru.
2) Zapsání textů do textových souborů .RTF.
3) Umístění všech potřebných řídicích znaků v souborech .RTF.
4) Vytvoření grafických objektů pro nápovědný soubor.
5) Vytvoření maker pro nápovědný soubor.
6) Výstavba projektového souboru.
7) Test a kontrola nápovědného souboru.
8) Zajištění provázanosti aplikace a nápovědného souboru.
Přitom body 4 a 5 nejsou nezbytné.
Při plánování nápovědného souboru je zapotřebí dodržet několik zásad. Nejprve bychom měli rozhodnout, do jakých podrobností bude náš nápovědný systém zacházet. S určitostí nebudeme popisovat základní vlastnosti, pokud víme, že náš nápovědný soubor bude součástí programu, který používají uživatelé s dostatečnými zkušenostmi práce ve Windows. Nápovědný soubor umožňuje vložit řídicí znaky, pomocí kterých při překladu rozhodneme, které části zdrojového textu mají být ve výsledném souboru obsaženy, a které ne.
Důležitou součástí každého nápovědného systému je menu a obslužná tlačítka. Měly by zde být obsaženy minimálně činnosti jako Obsah (Contents), Vyhledej (Search), O aplikaci, nebo případně další jako Prohlížecí tlačítka (Browse Buttons). Nejjednodušší cestou je spuštění nápovědy v některé z klasických aplikací pod Windows a dodržení jejího standardu.
Snad nejdůležitější činností této kapitoly je vybudování hierarchické struktury budoucího souboru (návaznosti jednotlivých témat (Topic)), aby nedocházelo ke zdvojování zdrojových textů, a aby postup vyhledávání s návazností jednotlivých témat byl smysluplný a intuitivní. Nabízí se zde také možnost senzitivního vyhledávání, tj. nacházíme-li se na nějakém klíčovém slově a stiskneme klávesu F1 (Shift + F1), otevře se nápovědný soubor na požadovaném tématu.
Příklad hierarchie plánování je uveden na obr. 3.
Obr. 3 . Hierarchická struktura témat nápovědného souboru
Pro vytvoření těchto zdrojových souborů je možno použít jakýkoli textový editor, který dovoluje zapisovat v .RTF formátu (Rich Text Format), např. editor MS-Word verze 2.0 nebo 6.0. Struktura textových souborů je následující :
* jednotlivá témata (v nápovědném souboru je tento celek představován názvem kapitoly a s ním souvisejícím textem, jež tvoří jednotlivou skokovou jednotku) musí být odděleny znakem tvrdé stránky (Page Break).
* každé téma musí mít jedinečný identifikátor (kontextový řetězec).
* každé téma může mít titulek neboli nadpis.
* téma může mít seznam klíčových slov na něj se odvolávajících. Tato klíčová slova slouží pro rychlý přístup pomocí vyhledávací metody (Search).
* každé téma může být zařazeno do prohlížecí sekvence, skupiny témat, která spolu logicky souvisejí a mezi kterými je možno rychle listovat pomocí tlačítek "<<" a ">>" (Browse Buttons).
Jestliže téma obsahuje více textu nebo grafiky, než je možno umístit do nápovědného okna, zajišťují Windows aplikace zobrazení rolovacího pravítka. Nápovědný soubor však umožňuje vytvoření ploch, které není možno rolovat. Tyto nerolovací plochy se objevují jako hlavičky témat. Jejich vytvoření zajistíme tak, že vybereme nadpis (případně i další odstavce v tématu) a nastavíme jejich charakteristiku na "Drž s následujícím" (pro MS-Word v menu Format položka Paragraph a v sekci Pagination zakřížkujeme položku Keep With Next. Jestliže máte zájem změnit podkladovou barvu této nerolovací sekce, nadefinujte ji v projektovém souboru .HPJ.
Ukázka zdrojového souboru včetně různých řídicích znaků je uvedena v kapitole č. 8 u řešeného příkladu.
Kód "#" (poznámka)
Musí být jedinečný a zajišťuje funkci identifikátoru tématu. Bez jeho zadání by nebylo možno se na téma odkazovat.
Použití : Umístíme kurzor před název tématu a vložíme poznámku # (postup pro MS Word - v menu Insert vybereme položku Footnote a do boxu Custom Footnote Mark zapíšeme znak #). Tento znak se objeví jak u tématu, tak i v poznámkové části dokumentu. Do této části pak zapíšeme kontextový řetězec.
Příklad : Téma # Tvorba rozpisky
Poznámka # tvorba_rozpisky //kontextový řetězec
Kontextový řetězec může obsahovat znaky A-Z, 0-9, tečku a podtržítko. Maximální délka kontextového řetězce je 255 znaků.
Příklad funkce kontextového řetězce :
Podtržený text představuje oblast, při jejímž výběru dojde ke skoku (v tomto případě zobrazení vyskakovacího okénka) na téma, jehož kontextový řetězec se nachází těsně za oblastí určující skok (tento text "tvorba_rozpisky" musí být psán jako neviditelný (hidden) a mezi ním a podtrženým slovem nesmí být žádná mezera). Na základě kontextového řetězce se dostaneme na stránku 2 obsahující text tématu popisujícího tvorbu rozpisky.
Kód "$" (poznámka)
Definuje nadpis tématu. Objevuje se pak, například v seznamu při použití akce BookMark. Systém vkládaní je stejný jako u kontextového řetězce.
Příklad : Téma #$ Tvorba rozpisky
Poznámka # tvorba_rozpisky //kontextový řetězec
$ Tvorba rozpisky //titulek
Titulek může obsahovat maximálně 128 znaků. Tato položka je nepovinná.
Kód "K" (poznámka)
Text napsaný za tímto znakem v poznámce se objeví v dialogovém boxu vyhledávání (Search). Pokud vybereme v nápovědném systému metodu Search, objeví se dva List Boxy. V prvním se objevují řetězce zadávané za poznámkou "K" a v druhém jim odpovídající titulky. Systém vkládaní je stejný jako u kontextového řetězce.
Příklad : Téma #K Tvorba rozpisky
Poznámka # tvorba_rozpisky //kontextový řetězec
K Rozpiska;Tvorba kusovníku;Kusovník; //klíčová slova
Jak je vidno z příkladu, je možno použít více klíčových slov pro jedno téma. Musí být však odděleny znakem ";". Maximální délka klíčových slov pro jednotlivé téma je 255 ANSI znaků. Tato klíčová slova nemohou být použita při senzitivním vyhledávání (nemají význam kontextových řetězců). Současně je možné použít stejné klíčové slovo u více různých témat. Při vyhledávání je rozlišíme pomocí příslušných titulků.
Tato položka je nepovinná.
Kód "+" (poznámka)
Definuje posloupnost témat (sekvenci) s určitou logickou soudržností, v níž se můžeme pohybovat pomocí tlačítek "<<" a ">>" v nápovědném souboru (Browse Buttons). Tyto tlačítka se nezobrazují standardně, nýbrž musí být nadefinované v projektovém souboru.
Příklad použití sekvence pro nápovědný soubor k standardnímu menu :
|
název tématu |
příslušnost k sekvenci (poznámka) |
|
Soubory menu |
menu:005 |
|
Nový |
soubory:005 |
|
Otevři |
soubory:010 |
|
Ulož |
soubory:015 |
|
Zavři |
soubory:020 |
|
Edit menu |
menu:010 |
|
Vyřízni |
edit:005 |
|
Kopíruj |
edit:010 |
|
Přilep |
edit:015 |
Jestliže se v nápovědném souboru dostaneme na téma odpovídající "Soubory menu" zviditelní se nám prohlížecí tlačítko ">>" a kliknutím na něj se přesuneme na téma "Edit menu". Jestliže se přesuneme na téma "Nový", můžeme se pomocí prohlížecích tlačítek přesouvat mezi tématy "Nový", "Otevři", "Ulož" a "Zavři". Je velmi vhodné vkládat číselné inkrementátory s určitou distancí, abychom mohli později vkládat mezi ně další. Systém vkládaní je stejný jako u kontextového řetězce.
Příklad : Téma #+ Tvorba rozpisky
Poznámka # tvorba_rozpisky //kontextový řetězec
+ rozpiska:005 //pozice v prohlížecí sekvenci
Tato položka je nepovinná.
Kód "*" (poznámka)
Definuje příznaky specifikující témata, které se v nápovědném překladači připojují do výsledného nápovědného souboru podmínečně. Tyto znaky jsou nepovinné, ale když jsou použity musí stát jako první v tématu. Příznaky mohou být alfanumerické řetězce, nejsou senzitivní a nesmí obsahovat mezery. Může být specifikováno více příznakových řetězců pro jedno téma, v tom případě musí být od sebe odděleny znakem ";". Tyto tvořící příznaky se pak uvádějí v projektovém souboru do BUILD nastavení nebo do [BUILDTAGS] sekce. Jsou-li obsaženy v této části projektového souboru, budou témata odpovídající těmto tvořícím příznakům zahrnuty do nápovědného systému. Systém vkládaní je stejný jako u kontextového řetězce.
Příklad : Téma #* Tvorba rozpisky
Poznámka # tvorba_rozpisky //kontextový řetězec
* ProVsechnyUzivatele //tvořící příznak
Tato položka je nepovinná.
Kód přeškrtnutý nebo dvakrát podtržený text
Indentifikuje text, pomocí něhož se uživatel může přemístit do jiného tématu pomocí jeho kontextového řetězce, jak bylo ukázáno u popisu vkládání kontextového řetězce. Při kliknutí na tento text dojde k přesunu na téma, jehož kontextový řetězec je umístěn bezprostředně za skokovým textem. Nesmí mezi nimi být žádná mezera.
Příklad:
Soubory Menumenu_soubory
skokový text kontextový řetězec
Nápovědný systém se však může skládat z více než jednoho nápovědného souboru. Proto existuje také možnost skoku do jiného souboru :
Soubory Menumenu_soubory@d:\sato\help.hlp
skokový text kon. řetězec cesta a jméno jiného .HLP souboru
V nápovědném systému může být použito více než jedno okno. Při skoku do sekundárního okna použijeme zápis :
skokový textkont_retezec>JmenoOkna.
Oba dva způsoby skoku je možno kombinovat :
skokový textkont_retezec@d:\sato\help.hlp>JmenoOkna
Kód jednou podtržený text
Definuje, které dočasné vyskakovací okénko bude zobrazeno, když uživatel selektuje definiční text. Při kliknutí na tento text dojde k zobrazení vyskakovacího okénka s obsahem na něž referuje kontextový řetězec. Tento musí být umístěn bezprostředně za definičním textem. Nesmí mezi nimi být ani mezera. Způsob zápisu je stejný jako u skokového textu.
Pokud obsahuje téma, na které je činěn odkaz více odstavců, pak je zobrazen jen obsah prvního odstavce. Pro zobrazení více odstavců je potřeba nastavit u nich charakteristiku "Drž s následujícím" (pro MS-Word v menu Format položka Paragraph a v sekci Pagination zakřížkujeme položku Keep With Next).
Kód neviditelný text
Specifikuje kontextový řetězec pro téma, které bude zobrazeno, když uživatel selektuje text bezprostředně se nacházející před ním (skokový nebo definiční).
Každá bitová mapa (obrázek), použitá v nápovědném systému, musí být uložena přímo v souboru .RTF nebo v samostatném souboru .BMP, .WMF, .SHG. Bitová mapa může mít maximálně 16 barev, a být vytvořena v tom rozlišení, v jakém bude použit nápovědný soubor. Pro připojení grafiky do nápovědného souboru existují dvě metody :
* umístění bitové mapy nebo meta souboru přímo do tématu,
* umístění referencí na bitovou mapu nebo meta soubor do tématu.
Přímé umístění :
Výhody:
Můžete vidět grafické objekty přímo při tvorbě zdrojových souborů s tématy.
Nemusíte umisťovat cesty ke grafickým objektům v projektovém souboru.
Nevýhody :
Můžete použít pouze MS-Word jako zdroj pro zdrojové soubory .RTF.
Můžete použít pouze inline grafiku, což znamená že nemůžete nechat obtékat grafiku texty podél grafiky.
Grafika obsažená v MS-Word prodlužuje dobu potřebnou k rolování nebo ukládání tématových souborů.
Nemůžete měnit grafiku uvnitř MS-Word. Musíte ji modifikovat ve vaší grafické aplikaci a pak ji reimportovat do MS-Word.
Nemůžete zde umístit hypergrafiku (grafiku doplněnou editorem horkých ploch SHED.EXE o horké plochy).
Vložením stejného grafického objektu na více místech dochází ke zbytečnému nárůstu zdrojového souboru.
Umístění
pomocí referencí :
Výhody a nevýhody jsou přesně opačné než při přímém umístění.
Grafické reference se tvoří s pomocí následující syntaxe :
{příkaz JménoSouboru}.
Je možno použít následující příkazy:
bmc zarovnává grafiku v tématu jako písmena, tzn. že grafika není obtékána textem a objeví se na místě, kde je zapsána reference. Přitom je možné, aby vložený text byl i uprostřed odstavce, výsledek bude stejný, jako by na tomto místě odstavce byl obrázek vložen přímo, to znamená, že příslušný řádek se roztáhne podle velikosti obrázku. Přeložený nápovědný soubor obsahuje jednoduché kopie grafických dat oddělené od textu.
bml zarovnává grafiku v tématu podle levého okraje. Text obtéká podél pravého okraje grafiky. Přeložený nápovědný soubor obsahuje jednoduché kopie grafických dat oddělené od textu.
bmr zarovnává grafiku v tématu podle pravého okraje. Text obtéká podél levého okraje grafiky. Přeložený nápovědný soubor obsahuje jednoduché kopie grafických dat oddělené od textu.
Jméno souboru může obsahovat pouze jméno, nikoliv cestu. Ta se zapisuje do projektového souboru .HPJ. Jestliže chceme umístit grafiku na začátek odstavce, umístíme referenci {bml(r) .BMP} na začátek odstavce. Jestliže chceme umístit grafiku na konec odstavce, umístíme {bml(r) .BMP} na konec odstavce. Objekt je obtékán pouze textem daného odstavce.
Tyto grafické objekty je možno také použít pro skoky, stejně jako skokový text a definiční text. Tedy podtrhnutím (jednoduchým nebo dvojitým) a kontextovým řetězcem za ním. Např. : {bml(r) .BMP}kont_retezec. Stejným způsobem se dají aktivovat nápovědná makra. Text musí být dvakrát podtržen, za ním stojí příkazový znak "!" a za ním jméno makra, např. : {bml(r) .BMP}!Search(). Při kliknutí na tento grafický objekt se otevře dialogový box pro vyhledávání.
Poznámka : při zápisu reference na grafiku {příkaz JménoSouboru} se používají klasické složené závorky, nikoliv závorky pro vkládání kódů polí (Field Codes), vyvolávané kombinací kláves Ctrl+F9!
Více horkých ploch (ploch, při jejichž selektování dojde k provedení nějaké akce) na vaší grafice vám zajistí její lepší využití. Na základě nadefinovaní hypergrafiky na daném objektu můžete provést tyto akce :
* skok na jiné téma,
* zobrazit vyskakovací okénko,
* aktivovat nápovědné makro,
* aktivovat rutiny v externích DLL knihovnách.
Pro vytvoření této grafiky se používá editor horkých ploch (Hotspot Editor - SHED.EXE). V něm je možno editovat soubory formátu .BMP, .DIB a .WMF. Výsledek je ukládán do formátu .SHG. Poněvadž editor horkých ploch není kreslící, musíte vytvořit veškeré obrázky mimo něj. Protože však editor horkých ploch pracuje v architektuře MDI, můžete najednou editovat více grafických objektů.
Po spuštění editoru horkých ploch vybereme v menu File příkaz Open a otevřeme požadovaný grafický objekt. Pro vytvoření aktivní horké plochy zmáčkneme pravé tlačítko myši na místě, kde chceme, aby tato plocha začínala a táhneme až do místa, kde má končit. Později můžeme její velikost měnit tak, jak je to obvyklé v aplikacích pod Windows. Po vytvoření aktivní plochy se automaticky otevře dialogový box pro nadefinování vlastností této plochy, případně na ni dvakrát klikneme a otevře se nám tentýž dialogový box, jak vidíme na obr. 4.
Význam jednotlivých nastavení vlastností horké plochy je následující :
Context String sem zapíšeme kontextový řetězec tématu, které se má zobrazit po kliknutí na danou plochu.
Type definuje typ provedené akce, a to buď Jump pro skok na jiné téma, Pop-up pro zobrazení vyskakovacího okénka anebo Macro pro spuštění nápovědného makra.
Atribute definuje, zdali je daná plocha v nápovědném souboru viditelná nebo ne. Tím je míněno orámování okraje horké plochy.
Hotspot ID specifikuje jedinečnou hodnotu dané plochy. Toto ID je užíváno vnitřně editorem horkých ploch a je automaticky inkrementováno. Uživatel si může zapsat vlastní ID, ale musí být jedinečné.
Bounding Box definuje polohu aktivní (hotspot) plochy v bodech (pixel).
Pro usnadnění práce s často se opakujícím nastavením, můžeme nadefinovat implicitní hodnoty, které budou vloženy do každé nově vytvořené horké plochy. A to vybráním položky Preference z menu Edit. Položky dialogového boxu jsou podobné jako u definice vlastností horké plochy, viz. obr. 5.
Obr. 4 .Tvorba horké plochy v obrázku
Obr. 5 . Nastavení implicitních hodnot pro nové horké plochy
Text jednotlivých témat chceme často doplnit obslužnými tlačítky, které mají význam jen v aktuálním tématu. Mohli bychom krátkodobě přidat obslužné tlačítko pod menu, ale to nelze umístit doprostřed textu.
Pokud chceme mít tlačítko uloženo uprostřed textu, musíme do textu vložit obrázek znázorňující tlačítko (přímo nebo pomocí grafické reference) a označit ho jako skokový text, případně definiční text. Bezprostředně za něj umístíme kontextový řetězec nebo nápovědné makro. Při přímém vložení obrázku do textu může výsledek vypadat následovně :Bližší
informace
o_uloze po stisku tlačítka.
Druhou možností je vytvořit samostatný soubor s obrázkem tlačítka v editoru horkých ploch na něj umístit horkou plochu s odkazem na příslušné téma. Přitom je vhodné nezobrazovat rámeček kolem horké plochy, mohl by působit rušivě. Hotový obrázek s horkou plochou pak připojíme pomocí příkazu {bmc TLACITKO.SHG} a dosáhneme stejného výsledku. Výhoda tohoto řešení se projeví při opakovaném použití stejného tlačítka na více místech nápovědného souboru. Výsledkem bude kratší nápovědný soubor.
Makra v nápovědném systému slouží pro zákaznickou tvorbu tlačítek a menu, nadefinování jejich funkcí, případně jejich změn oproti standardu a k vykonávání externích aplikací, jakož i funkcí z DLL knihoven. Nápovědná makra mohou být spouštěna v těchto případech :
* když je nápovědný soubor poprvé otevírán (toto makro se musí nacházet v [CONFIG] sekci projektového souboru), zde je možno použít jakékoliv makro,
* když uživatel selektuje jednotlivá témata (jestliže je makro umístěno v tématové poznámce označené "!" je provedeno vždy, když uživatel stane na daném tématu tj. při skoku na téma, při použití prohlížecích sekvencí (Browse Buttons), při výběru ze seznamu historie (History) a vyhledávání (Search)), zde však není možno manipulovat s menu ani s obslužnými tlačítky,
* když uživatel vybere tlačítko, položku menu nebo horkou plochu obsahující makro (tento způsob je popsán u tvorby grafických objektů).
Tvůrce nápovědného makra musí přesně dodržet tato pravidla :
* zápis makra je nezávislý na velikosti použitých písmen (not case-sensitive), takže můžete zapsat makro užitím velkých nebo malých písmen dle vlastní úvahy,
* oddělovat každé makro pomocí znaku středník ";",
* specifikování prázdných mezer v řetězci makra umístěním citačních značek okolo textu,
* vkládání speciálních znaků v citačních řetězcích předznačených znakem "\". Tyto znaky jsou ( " ) ( ' ) ( ` ) a ( \ ),
* dvojité apostrofy se používají na ohraničení parametrů v makru. Je-li však parametrem makra další makro, požívají se pro označení jeho parametrů znaky ( ` ' ). Př. :
CreateButton("time_btm","&Time","ExecProgram("cloc",0)") je chybně,
CreateButton("time_btm","&Time","ExecProgram(`cloc',0)") je správně,
* makro smí být obsaženo v jiném makru,
* jednotlivé makro může mít maximálně 512 znaků.
Tvůrce může využít následující nápovědná makra. Při tvorbě konkrétních nápovědných souborů se však zjistilo, že ne všechna makra je možno použít ve zdrojových textech (.RTF). Především nebylo možno použít makra pro manipulaci s menu a obslužnými tlačítky.
|
název |
činnost |
|
|
About() |
Zobrazí About dialogový box. |
|
|
AddAccelerator( klávesa, stav přepínačů, "makro" ) |
Zajistí přístup pomocí horkých kláves k danému makru. klávesa - virtuální hodnota klávesy ve Windows. stav přepínačů - specifikuje stav ALT, CTRL a SHIFT (0(nic), 1(Shift), 2(Ctrl), 3(Shift + Ctrl), 4(Alt), 5(Alt + Shift), 6(Alt + Ctrl), 7(Shift + Alt + Ctrl). makro - nápovědné makro, jež je spuštěno při stisku těchto horkých kláves. AddAccelerator(0x73,7,"ExecProgram(`cloc.exe',1)") |
|
|
Annotate() |
Zobrazí Annotate dialogový box. |
|
|
AppendItem( "menuID", "položkaID", "JménoPoložky", "makro") |
Přidává položku na konec menu, jež bylo vytvořeno makrem InsertMenu. menuID - jméno použité InsertMenu makrem k vytvoření položky. Nová položka je přidána do tohoto menu. položkaID - jméno, které je vnitřně použito ve WinHelp. Toto jméno se pak použije při volání maker DisableItem a DeleteItem. JménoPoložky - jméno zobrazené v menu. makro - makro, které bude spuštěno při výběru dané položky z menu. AppendItem("mnu_books", "mnu_tools", "&Tools", "JI(`tools.hlp', `first_topic')") |
|
|
Back() |
Zobrazí (maximálně 40) předcházející témata v Back seznamu. |
|
|
BookmarkDefine() |
Zobrazí Define dialogový box. |
|
|
BookmarkMore() |
Zobrazí More dialogový box. Používá se v případě, kdy je definováno více než devět bookmarků. |
|
|
BrowseButtons() |
Přidá prohlížecí tlačítka ("<<" a ">>"). |
|
|
ChangeButtonBinding( "tlačítkoID", "makro" ) |
Připojí nápovědné makro k nápovědnému tlačítku. tlačítkoID - identifikátor připojení tlačítka CreateButton makrem. Pro implicitní tlačítka je to btn_contents (Contents), btn_search (Search), btn_back (Back), btn_history (History), btn_previous (<<) a btn_next (>>). makro - makro, které se spustí při stlačení tlačítka. ChangeButtonBinding( "btn_contens", "JumpId(`dict.hlp',` dict_contents')") |
|
|
ChangeItemBinding( "položkaID", "PoložkaMakro") |
Připojí nápovědné makro na položku menu, která byla vytvořena pomocí makra AppendItem. položkaID - identifikuje položku použitou v AppendItem. PoložkaMakro - nápovědné makro, které je spuštěné při výběru této položky. ChangeItemBinding( "time_index", "ExecProgram(`clock', 0)") |
|
|
CloseWindow( "JménoOkna") |
Zavírá specifikované okno ať již hlavní nebo sekundární. JménoOkna - jméno okna, které chceme zavřít (pro hlavní je rezervováno slovo "main", sekundární okno se definuje v .HPJ v sekci [WINDOWS]). CloseWindow("keys") |
|
|
Contents() |
Zobrazí hlavní téma v nápovědném souboru. |
|
|
CopyDialog() |
Zobrazí Copy dialogový box. |
|
|
CopyTopic() |
Kopíruje veškerý text aktuálně zobrazeného tématu do Clipboardu. |
|
|
CreateButton( "tlačítkoID" ,"jméno", "makro") |
Přidá nové tlačítko do nástrojového pruhu. tlačítkoID - jméno užíváno vnitřně WinHelp. Jako parametr při volání maker DisableButton ... jméno - jméno na tlačítku (maximálně 29 znaků) Makro - nápovědné makro, které je spuštěné při výběru tohoto tlačítka CreateButton("btn_ideas", "&Ideas", "JumpId(`ideas.hlp',`directory')") |
|
|
DeleteItem("itemID") |
Odstraní položku z menu, jež byla přidána makrem AppendItem. itemID - identifikační řetězec užitý AppendItem makrem. DeleteItem("mnu_tools") |
|
|
DeleteMark( "TextováZnačka") |
Odstraní textové značky, jež byly přidány makrem SaveMark. TextováZnačka - text specifikovaný SaveMark makrem. DeleteMark("Managing Memory") |
|
|
DestroyButton( "tlačítkoID") |
Odstraní tlačítko přidané makrem CreateButton. tlačítkoID - identifikátor připojený k tlačítku makrem CreateButton. |
|
|
DisableButton( "tlačítkoID") |
Zneplatní tlačítko přidané makrem CreateButton. tlačítkoID - identifikátor připojený k tlačítku makrem CreateButton. |
|
|
DisableItem( "položkaID") |
Zneplatní položku menu přidanou makrem AppendItem. položkaID - identifikátor připojený k položce makrem AppendItem |
|
|
EnableButton( "tlačítkoID") |
Zplatní tlačítko zneplatněné makrem DisableButton. tlačítkoID - identifikátor připojený k tlačítku makrem CreateButton. |
|
|
EnableItem( "položkaID") |
Zplatní položku menu zneplatněnou makrem DisableItem. položkaID - identifikátor připojený k položce makrem AppendItem. |
|
|
ExecProgram( "PříkŘádek", stav) |
Spustí externí aplikaci Windows. PříkŘádek - příkazový řádek pro aplikaci, která má být spuštěna. stav - zobrazení aplikací (0 normální, 1 minimalizovaná, 2 maximalizovaná). ExecProgram("clock.exe",0) |
|
|
Exit() |
Ukončí WinHelp aplikaci. |
|
|
FileOpen() |
Zobrazí Open dialogový box. |
|
|
FocusWindow( "JménoOkna") |
Změní zaostření na specifikované okno (primární i sekundární). JménoOkna - jméno okna na které chceme zaostřit (pro hlavní je rezervováno slovo "main", sekundární okno se definuje v projektovém souboru .HPJ v sekci [WINDOWS]. FocusWindow("keys") |
|
|
GoToMark( "TextováZnačka") |
Skočí na značku uloženou makrem SaveMark. TextováZnačka - text specifikovaný SaveMark makrem. GoToMark("Managing Memory") |
|
|
HelpOn() |
Zobrazí Using Help soubor pro WinHelp aplikace. |
|
|
History() |
Zobrazí History okno (může obsahovat maximálně 40 témat). |
|
|
IfThen(IsMark( "TextováZnačka"), "Makro") |
Spouští makro, jestliže platí určitá podmínka. TextováZnačka - výsledek testu makrem IsMark. Makro - nápovědné makro, které je spuštěno při platnosti podmínky. IfThen(IsMark("Managing Memory"),"JI(`trb.hlp',`man_mem')") |
|
|
IfThenElse(IsMark( "TextováZnačka"), "Makro1", "Makro2") |
Spouští makro, jestliže platí určitá podmínka, v případě neplatnosti spouští druhé makro. TextováZnačka - výsledek testu makrem IsMark. Makro1 - makro, které je spuštěno při platnosti podmínky. Makro2 - makro, které je spuštěno při neplatnosti podmínky. IfThen(IsMark("Managing Memory"),"JI(`trb.hlp',`man_mem')", "JumpContents(`trb.hlp')") |
|
|
InsertItem( "menuID", "položkaID", "JménoPoložky", "makro", pozice) |
Vkládá položku menu na danou pozici existujícího menu. menuID - jméno použité InsertMenu makrem k vytvoření položky. Pro standardní menu WinHelp je to mnu_file (File menu), mnu_edit (Edit menu), mnu_bookmark (Bookmark menu), mnu_helpon (Help menu). položkaID - jméno, které je vnitřně použito ve WinHelp. Toto jméno se pak použije při volání maker DisableItem a DeleteItem. |
|
|
|
JménoPoložky - jméno zobrazené v menu. Pokud chceme umožnit přístup k položce také pomocí horkých kláves Alt+písmeno, použijeme před příslušným písmenem ve jméně položky znak "&". makro - makro, které bude spuštěno při výběru dané položky z menu. Při použití více maker je nutno je oddělit pomocí znaku středník ";". pozice - integer hodnota specifikuje, na které pozici se objeví nová položka (první pozice má index 0, oddělovací čáry se rovněž počítají). InsertItem("mnu_books", "mnu_tools", "&Tools", "JI(`tools.hlp', `first_topic')", 3) |
|
|
InsertMenu( "menuID", "JménoMenu", pozice) |
Přidává nové menu do WinHelp menu. menuID - položka užívaná vnitřně WinHelp systémem (parametr pro AppendItem makro). JménoMenu - jméno zobrazené na menu. pozice - integer hodnota specifikuje, na které pozici se objeví nová položka (první pozice má index 0). InsertMenu("menu_util", "&Utilites", 3) |
|
|
IsMark( "TextováZnačka") |
Determinuje, která značka uložená makrem SaveMark existuje. TextováZnačka - je tímto makrem testovaná (vrací TRUE nebo FALSE podle výsledku testu. |
|
|
JumpContents( "JménoSouboru") |
Skáče na hlavní téma ve specifikovaném nápovědném souboru. JménoSouboru - jméno cílového souboru pro skok. JumpContents("program.hlp") |
|
|
JumpContext( "JménoSouboru", ČísloKontextu) |
Skáče na téma identifikované kontextovým řetězcem. JménoSouboru - jméno cílového souboru pro skok. ČísloKontextu - kontextové číslo tématu v cílovém souboru (definuje se v .HPJ v sekci [MAP]). JumpContext("program.hlp", 801) |
|
|
JumpHelpOn() |
Skáče na téma Using Help souboru. Je to buď default WINHELP.HLP nebo v části [CONFIG] nadefinovaný makrem SetHelpOnFile. |
|
|
JumpId( "JménoSouboru", "KontextovýŘetězec") |
Skáče na téma se specifikovaným kontextovým řetězcem v nápovědném souboru. JménoSouboru - jméno cílového nápovědného souboru .HLP pro skok. KontextovýŘetězec - kontextový řetězec tématu v cílovém souboru. JumpId("second.hlp", "second_topic") |
|
|
JumpKeyword( "JménoSouboru", "KlíčovéSlovo") |
Otevírá identifikovaný nápovědný soubor, vyhledá tabulku klíčových slov a zobrazí první téma obsahující klíčové slovo. JménoSouboru - jméno cílového nápovědného souboru .HLP pro skok. KlíčovéSlovo - klíčové slovo pro vyhledávání pomocí Search. JumpKeyword("clock.hlp", "hands") |
|
|
Next() |
Zobrazí další téma v prohlížecí sekvenci. |
|
|
Not() |
Provádí reverzi hodnot True a False. |
|
|
PopupContext( "JménoSouboru", ČísloKontextu) |
Zobrazí téma identifikované kontextovým číslem. Toto číslo je zapsáno v [MAP] sekci. JménoSouboru - jméno cílového souboru pro skok. ČísloKontextu - kontextové číslo tématu v cílovém souboru (definuje se v .HPJ v sekci [MAP]). PopupContext("program.hlp", 801) |
|
|
PopupId( "JménoSouboru", "KontextovýŘetězec") |
Zobrazí téma ze specifikovaného souboru ve vyskakovacím okénku. JménoSouboru - jméno cílového souboru pro skok. KontextovýŘetězec - kontextový řetězec tématu v cílovém souboru. PopupId("second.hlp", "second_topic") |
|
|
PositionWindow( Xpozice, Ypozice, šířka, výška, stav, "JménoOkna") |
Nastaví velikost a pozici hlavního nebo sekundárního okna. Xpozice,Ypozice - definuje levý horní roh (v systému 1024 x1024). šířka, výška - definuje velikost okna. stav - zobrazení aplikací (0 normální, 1 minimalizovaná, 2 maximalizovaná). JménoOkna - jméno okna které chceme nastavit (pro hlavní je rezervováno slovo "main", sekundární okno se definuje v projektovém souboru .HPJ v sekci [WINDOWS]. PositionWindow(100,100,500,500,0,"Samples") |
|
|
Prev() |
Zobrazí předcházející téma v prohlížecí sekvenci. |
|
|
Print() |
Pošle aktuální téma na tiskárnu. |
|
|
PrinterSetup() |
Zobrazí Print Setup dialogový box. |
|
|
RegisterRoutine( "DLLjméno", "JménoFunkce", "SpecifikaceFormátu") |
Registruje funkci z DLL knihoven jako makro. V tématovém souboru se této registrace smí použít v poznámce a na horkých místech, jinak v [CONFIG] sekci. DLLjméno - jméno knihovny DLL. JménoFunkce - jméno funkce ve zdrojové DLL knihovně. SpecifikaceFormátu - specifikuje formát parametrů umístěných ve funkci (u unsigned short, U unsigned long, i short int, I long int, s near char*, S far char*, v void). RegisterRoutine("HELPLIB", "RetString", "S=iU") |
|
|
SaveMark( "TextováZnačka") |
Ukládá umístění aktivně zobrazeného tématu. GoToMark makro může být užito ke skoku na dané umístění. TextováZnačka - text užívaný pro identifikování umístění tématu. |
|
|
Search() |
Zobrazí dialogový box pro vyhledávací operaci. |
|
|
SetContents( "JménoSouboru", "ČísloKontextu") |
Označí specifikované téma jako hlavní téma v nápovědném souboru. JménoSouboru - jméno nápovědného souboru, který obsahuje požadované hlavní téma. ČísloKontextu - kontextové číslo tématu ve specifikovaném souboru (definuje se v sekci [MAP]). SetContents("program.hlp", 801) |
|
|
SetHelpOnFile( "JménoSouboru") |
Označí specifikovaný nápovědný soubor, který nahradí WINHELP.HLP. JménoSouboru - jméno nahrazovacího nápovědného souboru. SetHelpOnFile("myhelp.hlp") |
Po vytvoření všech předchozích objektů je zapotřebí je všechny spojit a přeložit do binárního kódu. K tomuto účelu slouží projektový soubor .HPJ. Pro vytvoření tohoto souboru je možno použít jakýkoli textový editor, jež nevkládá doplňující znaky, a musí být uložen v ASCII formátu. Tento projektový soubor obsahuje několik sekcí :
Specifikuje tématové soubory, které se použijí k výstavbě nápovědného souboru. Tato sekce je povinná. Formát zápisu v této sekci :
[FILES]
PROD_95.RTF ;Hlavní téma pro nápovědný soubor
Všechny soubory zde umístěné jsou hledány v ROOT nastavení. Jestliže tam nejsou, generuje překladač chybu.
Sekce [OPTIONS] musí být v souboru .HPJ uvedena jako první, neboť obsahuje hlavní nastavitelné parametry. Jsou to :
BMROOT nastavuje adresář, kde WinHelp hledá bitové mapy specifikované v bmc, bml a bmr referencích. Jestliže nápovědný projekt má BMROOT nastavení, není nutné vypisovat bitové mapy v [BITMAPS] sekci.
BMROOT = c:\help\bmp, d:\graphics\art
BUILD nastavení specifikuje které témata s určenými tvořícími příznaky budou vložena nebo vyloučena při výstavbě nápovědného souboru. Je možno použít následujících symbolů
()
& AND operátor
| OR operátor
~ NOT operátor
BUILD = (DEMO | MASTER) & TEST_BUILD
Budou připojena témata která mají buď DEMO, nebo MASTER příznak, a která mají současně TEST_BUILD příznak a témata bez příznaků (ta jsou připojována vždy).
COMPRESS nastavení specifikuje úroveň komprese. Pro nastavení komprese je možno použít těchto výrazů. Bez komprese NO, FALSE nebo 0. Pro střední kompresi MEDIUM. Pro maximální kompresi YES, TRUE, 1 nebo HIGH.
COMPRESS = TRUE
CONTENTS nastavení identifikuje kontextový řetězec nejvyšší úrovně neboli hlavní téma. Není-li uveden, je za něj považován kontextový řetězec prvního tématu v prvním zapsaném souboru v sekci [FILES]. Uvedené téma je zobrazeno při otevření nápovědného souboru, pokud není zadáno žádné požadované téma.
CONTENTS = main_contents
COPYRIGHT nastavení umístí uživatelův text do About dialogového boxu. Může obsahovat 35 až 75 znaků.
COPYRIGHT = řetězec
ERRORLOG nastavení zobrazuje chybová hlášení během překladu na obrazovku a zároveň je zapisuje do specifikovaného souboru.
ERRORLOG = CHYBY.TXT
FORCEFONT nastavení vytvoří nápovědný soubor, který zobrazuje text pouze s jedním druhem fontu.
FORCEFONT = JménoFontu
ICON nastavení identifikuje soubor s ikonami, které se zobrazí při minimalizaci nápovědné aplikace.
ICON = IkonSoubor
LANGUAGE mění třídicí řád v Search dialogovém boxu na jiný než anglický.
LANGUAGE = NázevJazyka
MAPFONTSIZE nastavení mapuje velikost fontů specifikovaných ve vašich tématových souborech na různou velikost, jež se zobrazí v nápovědném okně. To znamená, že při zápisu témat použijete jedné velikosti a překladač zajistí zobrazení pro požadovaný display.
MAPFONTSIZE = m[-n]:p
Všechny fonty ve zdrojovém souboru v rozsahu velikosti od m do n včetně, jsou změněny na velikost p.
MAPFONTSIZE = 12-24:16 všechny fonty mezi 12 až 24 jsou změněny na 16
MAPFONTSIZE = 12:16 všechny fonty 12 jsou změněny na 16
MULTIKEY nastavení specifikuje poznámkový znak k použití pro dodatečnou tabulku klíčových slov. Může být použit kterýkoli alfanumerický znak kromě "k" a "K". Při zadání požadovaného znaku je třeba uvažovat i jeho velikost, tedy "l" "L".
MULTIKEY = L
OLDKEYPHRASE specifikuje, zda bude k nápovědnému souboru připojena standardní tabulka frází (True, 1, ON, Yes), nebo ne (False, 0, OFF, No). Implicitní je True.
OLDKEYPHRASE = False
OPTCDROM nastavení optimalizuje nápovědný systém pro zobrazení na CD-ROM. Pro jeho aktivování je možno použít některou z hodnot : YES, TRUE, 1, ON.
OPTCDROM = TRUE
REPORT nastavení zobrazuje zprávy na obrazovce během překladu.
REPORT = ON
ROOT nastavuje adresář, ve kterém překladač vyhledává zdrojové soubory zapsané v projektovém souboru. Každá cesta může specifikovat jiný disk a plnou cestu nebo relativní cestu z projektového adresáře.
ROOT = c:\winhelp\helpdir
TITLE nastavení připojuje titulek maximálně 50 znaků do nápovědného souboru. Není vhodné v titulku používat znaky s diakritikou. Pro zobrazení titulku je použit systémový font, který tyto znaky nezná.
TITLE = Muj nazev
WARNING nastavení specifikuje, jakou úroveň informací má překladač zobrazovat. 1 obzvlášť závažné chyby, 2 důležité chyby, 3 všechny chyby a upozornění.
WARNING = 3
Výsledný nápovědný soubor obsahuje témata, jejichž tvořící příznaky jsou zapsány v této sekci. Tato sekce je nepovinná. Může obsahovat maximálně 30 příznakových slov. Při jejich zápisu nezávisí na velikosti písmen, ale nesmí obsahovat mezery. Problémy by mohly nastat jen při použití písmen s diakritikou. Anglické programy obvykle neumí vzájemně přiřadit např. "ž" a "Ž" a chápou je jako dva různé znaky. Na jednom řádku smí být zapsáno pouze jedno slovo.
[BUILDTAGS]
DEBUGONLY
TESTONLY
Sekce [ALIAS] připojuje jeden nebo více kontextových řetězců ke stejnému tématu. Protože kontextový řetězec musí být jedinečný pro každé téma, zajišťuje tato sekce způsob spojení nápovědných témat bez překódovaní vašeho souboru. Při jeho zápisu nezávisí na velikosti použitých písmen (problémy mohou způsobit jen písmena s diakritikou) a smí obsahovat tyto znaky : A-Z, 0-9, tečku a podtržítko. Tato sekce je nepovinná
[ALIAS]
KontextovýŘetězec = alias
Nápovědný systém podporuje kontextovou senzitivní nápovědu použitím sekce [MAP], ve které je možno ztotožnit kontextový řetězec, případně alias řetězec s kontextovým číslem. Pojem senzitivní nebo kontextová nápověda znamená, že pokud se v aplikaci nacházíme na konkrétní položce a stiskneme klávesu F1 vyvolávající nápovědu (případně Shift+Fl), je zobrazeno téma popisující aktuální položku a ne hlavní téma nápovědného souboru.
Tato sekce je nepovinná. Chceme-li však, aby nám nápovědný systém spolupracoval např. s aplikacemi vytvořenými v databázi MS-Access, musíme provést tuto sekci. Dané číslo je pak v Accessu zapsáno ve vlastnostech IDContents. Sekci [MAP] je možno provést těmito způsoby (využívá konvencí jazyka C)
[MAP]
EditWindow 0x0001
ControlMenu 0x0002 nebo
dcmb_scr 30 ;komentář
dmxi_scr 31 ;komentář nebo
#define vscroll 0x010A /*komentář*/ doporučeno nebo
#include <sample.h>
kde soubor sample.h obsahuje výše uvedené definice
Pokud chceme vkládat bitové mapy, které se nenacházejí ani v ROOT ani v BMROOT specifikovaných adresářích tak využijeme sekce [BITMAPS].
[BITMAPS]
HLAVNI.BMP
C:\BITMAP\DUMP02.BMP
Sekce [CONFIG] nápovědného projektového souboru registruje DLL funkce a makra, která WinHelp spustí při otevření.
[CONFIG]
RegisterRoutine("bmp","HDisplayBmp","USSS") ;zobrazí vnější bitovou mapu Windows
CreateButton("777","&About","About ()") ;přidá tlačítko pro otevření About okna
Sekce [WINDOWS] projekčního souboru definuje velikost, umístění a barvy primárního a sekundárního okna.
typename = "titulek", (horizontálníPozice, vertikálníPozice, šířka, výška) umístění, (zákaznickáRGB), (nerolovacíČástRGB), specifikaceSekundárníhoOkna
pro primární okna musí být typename specifikovaný slovem main, je-li specifikace sekundárního okna 1, je zobrazeno na povrchu ostatních oken
[WINDOWS]
main = "Hlavni",(0,0,1023,1023), , ,(192,192,192)
sekundarni = "Sekudarni",(222,226,725,486) , , , (192,192,192),1
Pro multimediální elementy je vyhrazena sekce [BAGGAGE] a je nepovinná.