Umíme to s Delphi, 57. díl – vytváření nápovědy

V dnešním díle si ukážeme, jak doplnit svou aplikaci o kontextovou nápovědu. Vysvětlíme si hlavní principy nápověd a krok za krokem projdeme jednotlivé body, které musíme při jejím vytváření zkompletovat. V závěru si předvedeme praktický postup ručního napsání nápovědy.
Před několika týdny se na mě obrátil jeden ze čtenářů s velmi zajímavým námětem: tvorbou nápovědy. Po kratší úvaze jsem mu musel dát za pravdu – skutečnost, že jsme se dosud nápovědě nevěnovali, je poměrně závažným nedostatkem, který je nutné co možná nejdříve napravit. Důvodů existuje celá řada – kvalitní nápověda je (měla by být) nedílnou součástí každé aplikace, se kterou to myslíme alespoň trochu vážně; její vytváření není nikterak obtížné, ale na druhou stranu ani v nejmenším intuitivní. Nevíte-li, jak na to, asi nápovědu nevytvoříte, protože – jak záhy seznáte – některé (nezbytné) kroky jejího vytváření byste logicky neodvodili ani za týden intenzivního přemýšlení.

Systém nápovědy

Systém nápovědy je nesmírně důležitým prvkem, který spolurozhoduje o úspěchu nebo neúspěchu aplikace. Vytváření helpů se v každém případě vyplatí věnovat dostatek pozornosti. Přestože snad žádný z programátorů nemá psaní nápověd příliš v oblibě, měla by být perfektně zpracovaná nápověda nedílnou součástí každého programu. Pravdou je, že v mnoha případech tomu tak není, nicméně rád bych tímto apeloval na všechny, kteří považují nápovědu za jakousi zbytečnou „práci navíc“ – pokud nenalezne nápovědu profesionál, nic tak hrozného se neděje. Nenajde-li ji však začátečník, s vaším programem pracovat prostě nebude (platí to skutečně častěji, než by si člověk byl ochoten připustit).

Zvláště u rozsáhlejších aplikací nebývá vždy programátor autorem nápovědy. Help často tvoří jiné osoby, které jsou ve velkých firmách placeny právě a jen za psaní nápověd. Vždy je však nezbytně nutné, aby vývojář programu a autor nápovědy spolu úzce spolupracovali. Autor nápovědy ví, „co by v nápovědě mělo být“, a vývojář mu poskytne konkrétní informace o tom, „jak to v programu funguje“.

U menších aplikací samozřejmě bývá autor nápovědy a vývojář programu jednou osobou. V takovém případě je nutné znát strukturu souborů nápovědy a způsob jejího vytváření. Bohužel – tvorba nápovědy (bez použití některých specializovaných produktů určených přímo na vytváření helpů) není úplně jednoduchá a zábavná práce.

Plovoucí nápověda – hint

S jednou formou nápovědy jsme se již v našem seriálu setkali. Zabývali jsme se plovoucí nápovědou. Celá řada komponent (prakticky všechny, které jsou vidět za běhu programu) má vlastnost Hint, do níž můžeme napsat text, který má být plovoucí nápovědou. Kromě této vlastnosti je možné vždy nastavit vlastnost ShowHint (logická hodnota), která udává, má-li se nápověda u příslušné komponenty zobrazovat nebo nikoliv.

Ještě „šikovnější“ než vlastnost ShowHint je však vlastnost ParentShowHint, kterou mají všechny komponenty disponující vlastností ShowHint. Tato vlastnost má také logickou hodnotu, a je-li nastavena na True, bude plovoucí nápověda zobrazena v těch případech, kdy to povoluje vlastnost ShowHint rodičovské komponenty. Raději uveďme příklad: umístíte-li na formulář pět komponent (a nastavíte jim ParentShowHint na True) a formuláři nastavíte vlastnost ShowHint na True, bude plovoucí nápověda u každé z komponent zobrazena vždy bez ohledu na hodnotu její vlastní hodnoty ShowHint. Tak je možné „centrálně“ vypnout zobrazování plovoucích nápověd v určité části programu, např. v určitém okně apod., třeba jako reakci na uživatelovu volbu.

Ještě připomeňme, že globálně je možné nastavovat řadu vlastností spojených se zobrazováním této nápovědy (např. barvu plovoucího políčku, časové zpoždění jejího zobrazení, dobu zobrazení apod.). Provádí se to pomocí objektu Application a jeho vlastností (HintShortPause, HintColor a řada dalších).

Vytváření hlavní nápovědy: „ručně“ a pomocí nástrojů

Plovoucí nápověda by však neměla být jedinou. Hlavním nositelem informací pro uživatele by měla být kontextová, hlavní nápověda.

V zásadě existují dva hlavní způsoby vytváření systému nápovědy: ručně nebo za použití specializovaných nástrojů. V poslední době již (naštěstí) existuje poměrně dost nástrojů, které vytváření nápovědy maximálně usnadňují. Jmenujme například ForeHelp, nebo RoboHelp.

Při použití některého z těchto nástrojů je vývojář v podstatě „odstíněn“ od detailů, jakými jsou např. přesná struktura souboru nápovědy. I tak mu ale jejich znalost může usnadnit práci, už tím, že ví, co se po něm v jednotlivých fázích tvorby „vlastně chce“. V následujících podkapitolách se podíváme na tvorbu nápovědy bez těchto nástrojů.

Kroky při vytváření nápovědy

Postup při vytváření nápovědy je možné rozdělit do několika kroků, které si následně podrobněji rozebereme.
  • Analýza zákazníka;
  • Logické rozdělení nápovědy, určení témat;
  • Vytvoření vlastních textů nápovědy – formát *.RTF;
  • Vytvoření souboru projektu;
  • Kompilace nápovědy;
  • Včlenění nápovědy do aplikace.

1. Analýza zákazníka

Při tvorbě nápovědy je třeba přihlížet k tomu, kdo bude nápovědu číst. Toto posuzování je nutno provádět ze dvou pohledů:

  • Je rozdíl psát help určený pro počítačové profesionály a naopak pro začínající uživatele, žáky, studenty, sekretářky apod.
  • Je rozdíl psát nápovědu pro textový editor a pro software umožňující vyplňování daňových formulářů. Ve druhém případě je nanejvýš vhodné zakomponovat do nápovědy také témata, která bezprostředně nesouvisí s programem a jeho ovládáním – např. rady k jednotlivým daním apod.

2. Logické rozdělení nápovědy, určení témat

Nejprve uveďme obecnou strukturu nápovědy, tedy elementy, ze kterých se nápovědy (a dále jejich jednotlivá témata) skládají.

Základními prvky, ze kterých se nápovědy skládají, jsou tzv. témata (Topics). Téma je v zásadě ucelená jednotka informací, která poskytuje help k určité položce programu, například položka v menu, dialog apod. Jedno téma helpu zabírá později jednu stránku (která může být samozřejmě delší než jedna obrazovka, ale pak scrolluje), při přechodu na jinou stránku výsledného helpu přecházíme na jiné téma.

Každé téma se skládá z dalších částí (obsahuje tyto části):

  • Browse Sequence – pořadí prohlížení, určuje, kolikáté v pořadí bude téma při sekvenčním prohlížení.
  • Context Number – kontextové číslo, identifikátor (související s kontextovým řetězcem). V Delphi následně nastavíme toto číslo ve vlastnosti HelpContext komponenty, k níž se téma vztahuje.
  • Context String – kontextový řetězec, alfanumerický identifikátor, který jedinečně určuje dané téma. Nesmí obsahovat mezery, souvisí s tvorbou hypertextových odkazů.
  • Footnotes – řídící poznámky, pomocí kterých se u tématu definují některé vlastnosti.
  • Hot Spots – doslova žhavá místa – zpravidla hypertextové odkazy, mohou jimi být i obrázky.
  • Keywords – klíčová slova, slova (nebo fáze) spjatá s tématem. Využívá se jich při hledání. Je-li jich pro dané téma víc (což nastává skoro vždy), oddělují se středníky.
  • Topic Text – text tématu, vlastní text popisující dané téma. Může obsahovat odkazy na jiná témata, obrázky, případně vložený kód (makra).
  • Topic Title – nadpis tématu, obvykle by se měl objevit na prvním řádku obrazovky.
Pokud tedy máme hrubou představu o jednotlivých tématech, jejich klíčových slovech a dalších elementech, můžeme se pustit do nejnepříjemnější části tvorby helpu – vytvoření *.RTF souboru.

3. Vytvoření vlastních textů nápovědy - *.RTF

K vytváření souborů *.RTF je možné použít libovolný editor, který dovoluje vytvářet poznámky pod čarou, dvojitě podtržený text a skryté znaky v textu. To vše bude totiž (bohužel) zapotřebí. Mezi editory, které splňují tyto požadavky, patří např. MS Word, WordPerfect nebo AmiPro.

Při vytváření textu tématu napište nadpis, můžete jej libovolně zvýraznit, a pokračujte sepsáním vlastního textu tématu. Je možné všechna témata psát do jediného souboru *.RTF a oddělovat je konci stránek (v MS Wordu 2000 Vložit – Konec… - Konec stránky). Help se ovšem může skládat i z více souborů *.RTF.

Po napsání textů jednotlivých témat je nutné vytvořit tzv. neviditelné (řídicí) části. K tomu slouží právě poznámky pod čarou. Doporučuji umístit kurzor na začátek příslušné stránky a tam zvolit vložení poznámky pod čarou (v MS Wordu 2000 Vložit – Poznámka pod čarou…). Poznámek je nutné vložit více a jejich význam závisí na použitém symbolu (viz tabulka):

Symbol Význam
+ Browse Sequence
# Context String
K Keywords
$ Topic Title

Kromě těchto symbolů se ještě (nepříliš často) používá komentář (@) a příznaky pro podmíněný překlad <).

Posledním bodem je zpravidla nadefinování odkazů (Hot Spots). Při vytváření Hot Spotu se požadovaný text dvojitě podtrhne a ihned za něj (bez mezery) se napíše kontextový řetězec tématu, na který se má skočit. Tento kontextový řetězec je nutné označit a skrýt (skrytý text).

Nakonec soubor uložte jako *.RTF. Na pojmenování nezáleží, nebude mít na jméno výsledného souboru s nápovědou <.HLP) vliv.

4. Vytvoření souboru projektu

Projektový soubor nápovědy je obyčejný textový soubor, takže jej můžete vytvořit v libovolném editoru (např. Notepad Poznámkový blok a další). Pojmenujeme jej tak, jak se má nakonec jmenovat výsledný soubor s nápovědou (tedy *.HLP).

Projektový soubor obsahuje informace potřebné ke zkompilování *.RTF souboru do souboru *.HLP. Je tvořen sekcemi v hranatých závorkách. Možných sekcí je poměrně dost, zpravidla se však nepoužívají všechny.

Příklad projektového souboru (včetně názvů několika nepoužitých sekcí):

[OPTIONS]
TITLE=Text, který se objeví v záhlaví okna s nápovědou
DEFFONT=Písmo
CONTENTS=Kontextový řetězec hlavního tématu
COMPRESS=Stupeň komprese souboru, je vhodné nakonec nastavit High
ERRORLOG=Soubor pro ukládání chybových hlášek vzniklých při překladu

[FONTS]  ; použité fonty
Arial=Arial CE

[FILES]  ; uvedení souborů *.RTF
Soubor1.RTF

[MAP]    ; mapování kontextových řetězců na čísla použitelná v Delphi
Řetězec1  1
Řetězec2  2
...

5. Kompilace nápovědy

Pro kompilaci nápovědy se používá některý z Help kompilátorů. S Delphi se dříve dodával kompilátor HC31.EXE. S verzí Delphi 5 Enterprise se momentálně dodává celý nástroj pro tvorbu nápověd – Microsoft Help Workshop. Tento nástroj se spouští souborem HCW.EXE, který (při standardní instalaci Delphi) naleznete v adresáři Delphi5\Help\Tools\HCW.EXE. V tomto programu je možné vytvořit také projektový soubor (a to poněkud interaktivněji než v Poznámkovém bloku:-)). Ať jste již projektový soubor získali jakkoliv, můžete jej zde přeložit (volba Compile).

6. Včlenění nápovědy do aplikace v Delphi

Při vývoji aplikace v Delphi je nejprve nutné stanovit, který soubor s nápovědou se k aplikaci vztahuje. To se nastaví např. v hlavním menu: Project – Options, záložka Application, položka Help file. Takto zadané jméno souboru je hodnotou vlastnosti HelpFile třídy TApplication.

Za předpokladu, že v projektovém souboru nápovědy jsou správně „namapované“ kontextové řetězce na čísla, stačí nyní nastavovat vlastnosti HelpContext jednotlivých komponent. Komponenta, která má zaměření (focus), pak za běhu vyvolá takové téma nápovědy, jehož Context Number odpovídá hodnotě HelpContext této komponenty.

Další možností, jak programově vyvolat nápovědu, je zavolání metody HelpContext objektu Application. Následující příklad vyvolá téma s kontextovým číslem 1:

Application->HelpContext(1);

Vytváření nápovědy prakticky

Tolik tedy ke stručnému teoretickému popisu problematiky. Protože si nejsem jist, zda na jeho základě bude případný zájemce schopen nápovědu skutečně vytvořit, ukážeme si důležité body také prakticky.

Následující výpis umístěný mezi dvěma vodorovnými čarami demonstruje jedno téma nápovědy. Protože však některé prvky souboru rtf (poznámky pod čarou, skrytý text) se na webové stránce poměrně obtížně ukazují, dovolím si vše podstatné ještě slovně popsat:

  • před nadpisem (Instalace produktu) jsou vloženy tři poznámky pod čarou. Poznámka $ znamená název tématu (a níže, skutečně pod čarou, bychom za normálních podmínek viděli, že názvem je „Instalace produktu“, # udává Content String (v našem případě „instalace“), K specifikuje klíčová slova (v našem případě opět „Instalace produktu“).
  • slovo „Konvertoru“ v prvním řádku textu je dvojitě podtržené a hned za ním, bez mezery, následuje skrytý text, jehož obsahem je skrytý text označující téma, na které se má skočit.
  • ve složených závorkách jsou obrázky, které budou vloženy do nápovědy.

Instalace produktu

Instalace Konvertoru je mimořádně jednoduchá, intuitivní a uživatelsky přítulná.

Produkt je dodáván v jediném spustitelném souboru: LaTeXToHTML.exe. Instalace se provede spuštěním tohoto souboru. Průběh instalace je stejný jako u většiny dalších (dobrých) programů pod OS Windows.

Po spuštění instalace nejprve vyberete cílový adresář:

{bmc COREL035.bmp}

Chcete-li změnit nabídnutý adresář, klikněte na tlačítko Procházet.

Pak vyberete složku (v nabídce Start - Programy), do které chcete umístit spouštěcí ikonu programu. Tato ikona bude v každém případě umístěna také na ploše Windows.

{bmc COREL036.bmp}

Jakmile kliknete na tlačítko Další, proběhne vlastní instalace.

Na poslední obrazovce pouze zvolíte, chcete-li Konvertor hned spustit, a stisknete tlačítko Dokončit:

{bmc COREL037.bmp}

Poznámka, která není součástí originálního souboru *.rtf: zde by byly vidět poznámky pod čarou, zhruba v tomto tvaru:

$Instalace produktu

#instalace

KInstalace produktu

Nyní si ukážeme fragment projektového souboru nápovědy:
[OPTIONS]
TITLE=Konvertor - nápověda
CONTENTS=Konvertor
COMPRESS=High
ERRORLOG=t2h.err

[FONTS]  ; použité fonty
Arial=Arial CE

[FILES]  ; uvedení souborů *.RTF
t2h.RTF

[MAP]  ; mapování kontextových řetězců na čísla použitelná v Delphi
Instalace  1
Obecne     2
Prostredi  3
...

Výsledná stránka může vypadat třeba takto: Klepněte pro větší obrázek

Na závěr

Dnešní díl seriálu týkající se struktury nápovědy a vytváření helpů si nekladl za cíl stát se kompletním referenčním popisem této problematiky, spíše se snažil seznámit vás se základními pojmy a rámcovými postupy. Je vidět, že ruční vytváření nápovědy skutečně nepatří k nejpříjemnějším programátorovým zábavám, nicméně jak bylo uvedeno v úvodu, je možné použít některý z programových nástrojů, které řadu dnes popsaných činností provedou za nás.
Diskuze (13) Další článek: Skener Visioneer 4800: jednoduchost sama

Témata článku: Software, Windows, Programování, Klíčová vlastnost, Hlavní téma, Soubor, Celý nástroj, Browse, Specializovaný produkt, Apod, Fonts, Jednotlivé položky, Help, Mezera, Vodorovné okno, Případný zájemce, Options, Fragment, Hlavní způsob, Jednotlivé komponenty, Jednotlivý produkt, Přesná struktura, Vytváření, Originální soubor, DEL


Určitě si přečtěte

Týden Živě: On fakt dnes ještě někdo stahuje filmy z Ulož.to?

Týden Živě: On fakt dnes ještě někdo stahuje filmy z Ulož.to?

** Kauza Ulož.to a proč my dva už (moc) newarezíme ** Windows 10X existují, ale nabízí se otázka proč ** Nissan ukázal vizi kanceláře v podobě karavanu

Jakub Čížek, Vladislav Kluska | 152

Jakub ČížekVladislav Kluska
Týden ŽivěVideo
Vybíráme nejlepší monitory: Od úplně levných až po displeje na rozmazlování očí

Vybíráme nejlepší monitory: Od úplně levných až po displeje na rozmazlování očí

** Vybrali jsme nejlepší monitory na práci i pořádné hraní ** Nejlevnější monitor s kvalitním panelem nestojí ani tři tisíce ** Rozlišení 4K a větší obrazovka už není nedostupný luxus

David Polesný | 31

David Polesný
Monitory
Vážně dnes ještě někdo krade Adobe? Video můžete stříhat zdarma v Resolve a fotky i vektory zvládne Affinity

Vážně dnes ještě někdo krade Adobe? Video můžete stříhat zdarma v Resolve a fotky i vektory zvládne Affinity

** Kde jsou ty doby, kdy měl skoro každý doma Photoshop ** Photoshop a Premiere Pro od kamaráda nebo z warezu ** Dnes už to nemá smysl, existuje totiž hromada laciných alternativ

Jakub Čížek | 90

Jakub Čížek
Grafický editorStřih videa
Micro:bit V2: Tuto destičku plnou čipů dokáže naprogramovat i vaše babička

Micro:bit V2: Tuto destičku plnou čipů dokáže naprogramovat i vaše babička

** Chcete se teď hned naučit programovat čipy? ** Nechcete nic instalovat a číst zdlouhavé manuály? ** Naprogramujeme si Micro:bit, který zahraje Tichou noc

Jakub Čížek | 35

Jakub Čížek
Pojďme programovat elektronikuProgramování pro děti
Vy a počítač: Virtuální plochy ve Windows mají smysl, používá je třetina čtenářů
Vladislav Kluska
Jak používáte počítačWindows 10Ankety
Technici nestíhají. Cetin dočasně přerušil zavádění VDSL bondingu
Lukáš Václavík
CETINPřipojení k internetu