Vytváření helpu #2 - Builder.cz - Informacni server o programovani

help

help

10. dubna 2002, 00.00 | Dnes se podíváme na to, jak se dají vytvářet CNT soubory. Dále se podíváme, jak zařadit vytvořené soubory nápovědy do projektů Delphi, C++ a Visual Basicu. Tak pojďme na to!

Dnes se podíváme na to, jak se dají vytvářet CNT soubory. Dále se podíváme, jak zařadit vytvořené soubory nápovědy do projektů Delphi, C++ a Visual Basicu. Tak pojďme na to!

Psaní CNT souborů je stejná brnkačka jako HLP soubory samotné. Těm jež ještě žádný takovýto soubor nedělali bych doporučil, aby si otevřeli Help Workshopem např. CNT soubor nápovědy samotného programu. Pomůže nám to pochopit, že CNT soubor je pouze stromovou reprezentací klasických HLP souborů¹. Mimo to si také uvědomíme, že nápověda by měla být vytvářena v nějaké logické posloupnosti — systému.

Ale dost teoretizování! Prozkoumáte-li si tento soubor, zjistíte, že nadpisy jsou de-facto pouhé složky a netvoří žádný odkaz. Zato jednotlivé topiky jsou odkazem samotným. Kde je odkaz definován skrze text, který jste v RTF souborech vkládali do poznámky #. Můžete zadat i jméno HLP souboru². Dále byste zde mohli uvést jméno okna, do kterého se má daná karta otevřít. Vzhledem k tomu, že jsem vás při psaní HLP souborů neučil, jak se vytvářejí vlastní okna, tak tuto položku nevyplňujte³.

Chcete si nyní vytvořit vlastní CNT soubor? Není nic jednoduššího než kliknout File | New a vybrat Help contents. Po kliknutí na první pravé tlačítko Edit by se měl zobrazit dialog Default Help Information. Zde napište jméno HLP souboru, pro který píšete svůj CNT soubor. Výchozí okno nevyplňujte viz. předcházející a do názvu helpu si napište svůj text.

A již zbývá jen naklikat jednotlivé nadpisy a do nich vložit jednotlivé položky (topic) s nějakým odkazem. Bylo by dobré dodržet zažitou konvenci a položky jednotlivých složek vždy posunou o jednu úroveň doprava — tlačítko Move Right. Nakonec vše uložit do stejné lokace jako je samotný HLP soubor. A můžete se kochat vlastním výtvorem. Asi správně předpokládám vaši znalost, že k zobrazení CNT souboru stačí otevřít HLP soubor a váš CNT soubor je v záložce Contents.

Máme-li již vytvořený HLP soubor můžeme ho začlenit do naší aplikace. Nejdříve si je nutno zodpovědět jednu otázku. Je hlavním souborem nápovědy pro aplikaci. Jestliže ano, pak stačí v Delphi v dialogu Project Options (Project | Options) na kartě Application vybrat v Help file náš HLP soubor.

Do samotné aplikace je ještě dobré přidat menu Help. Což můžete udělat sami — ručně či přes kontextové menu vybrat Insert from Template a zde vybrat položku Help.

K jednotlivým MenuItem je ještě nutné přidat OnClick, ve kterém zavoláte jeden ze čtyř možných příkazů, který vyvolá nápovědu. Všechny čtyři příkazy jsou funkce, kde návratová hodnota vypovídá o jejich úspěšnosti v tom smyslu, že vrací false jen tehdy, není-li zadaný žádný help soubor v Application.HelpFile. Ve všech ostatních případech vrací true a to i v případě, že daný odskok neexistuje!

HelpJump(JumpID), kde JumpID je nějaký string, který je definovaný v Map. V našem případě by to mohlo být např. LANGUAGE. Po vyvolání příkazu se zobrazí help s danou kartou. Příkaz, který zobrazí daný help, pak vypadá takto:

HelpContext(Context), kde Context označuje číselnou hodnotou, která je definovaná jako protipól textu v Map. Po vyvolání příkazu se stejně jako v předešlém případě zobrazí help s danou kartou.

HelpCommand(Command; Data), kde Command označuje příkaz, který je předán WinHelpu. Existuje množství příkazů, které mu mohou být předány. Některé z nich vyžadují předávat i smysluplnou hodnotu v parametru data, jiné ne. Nejjednodušší bude, když se zmíním o tom, že seznam možných příkazů je zmíněn v souboru ...Delphi\Source\RTL\Win\Windows.pas, kde hledejte { Commands to pass to WinHelp() }. Většina příkazů lze snadno odvodit z názvů jednotlivých konstant. Mezi nejdůležitější asi patří: HELP_INDEX, HELP_CONTEXT, HELP_CONTENTS, HELP_FINDER a HELP_QUIT. Myslím si, že je zcela zřejmé, že tímto příkazem lze nahradit zbylé tři tj. HelpJump...

Posledním příkazem je HelpKeyword(Keyword), kde Keyword je některé klíčové slovo uvedený v poznámce pod čarou nazvanou jako K. Např. pro zobrazení karty jazyka by to bylo Jazyk viz. obrázek Poznámky pod čarou.

Toto je manuální způsob, kdy si vyvolání nápovědy ošetřujete sami. Ale častěji to dělá sám program např.

Potřebujete-li ve vaší aplikaci vyvolávat karty z různých HLP souborů, je nutné před tímto voláním, ať již jakýmkoliv z čtyř předcházeních příkazů, změnit aktivní HLP soubor.

Konečně, pro příznivce C++ tu máme návod, jakým způsobem se dají vytvořené soubory nápovědy začlenit do projektů. Samozřejmě bych zde, mohl ukázat zcela shodný postup jako jsem to udělal pro Delphi. Ale nejsem si tak jistý v C++ jako v Delphi. A hlavně by to bylo asi zbytečné, když už to někdo udělal za mne. Myslím si, že tento manuál, Connecting WinHelp to C++/MFC Programs by Don Lammers, je dostatečně výmluvný. Má jen jedinou nevýhodu. Je v angličtině. Doufám, že tuto skutečnost nějak překousnete.

Aby se nám z těch jazyků nezatočila hlava, tak ještě přidáme otáčky! Máme tu další jazyk a to Visual Basic. Stejně jako u předchozího vás trošičku ošidím. Nabízím vám manuál od stejného autora jako pro C++ — Connecting WinHelp to Visual Basic Programs. Asi nemusím zdůrazňovat, že je opět v angličtině. Víte stejně dobře jako já, že skutečný programátor se bez angličtiny neobejde. Tudíž by to pro vás neměl být až takový problém.

K WinHelpu je to vše.

1. – jeden CNT soubor může být obsahem resp. obsahovat odkazy na jiné HLP soubory
2. – není nutné, používáte-li jen jeden HLP soubor
3. – výchozí okno je dosazeno automaticky