Delphi - HTMLHelp készítése és felhasználása Delphi-ből

HTMLHelp 1. rész

forráskód letöltése
Új cikksorozatunkban a HTML Help készítését és az elkészült súgó állomány felhasználási területeit vesszük szemügyre hétről-hétre.

A HTML Help elkészítéséhez a Microsoft HTML Help Workshop nevű programját használjuk fel, mely ingyenesen letölthető az internetről. (Aktuálisan 3-4 MB körül van a letöltendő állomány.) A példaprogramok készítése közben ennek a használatát is ismertetjük részletesen.

Bár a Delphi-ben nem találtunk támogatást a HTML Help felhasználáshoz, ennek ellenére még akár a Delphi 3-as verziójából is viszonylag könnyedén megtehetjük ezt.

A cikksorozatban kitérünk azokra a felhasználási területekre is, melyből egyértelműen látható lesz, hogy egy HTML Help állomány elkészítésével nem csak a hagyományos értelemben vett súgó állományt kapunk, hanem azt sok más céllal is felhasználhatjuk.

A cikksorozat teljesen a kezdő szintről indul, így az is belevághat a megismerésbe, aki még soha nem foglalkozott a címben említett témával. A cikkek megértéséhez persze nem árt, ha a Delphi-t már használta az Olvasó, valamint alapfokon jó, ha tisztában van a web lapok készítésével, a HTML nyelvvel. Microsoft HTML Help Workshop programja aktuálisan a http://msdn.microsoft.com/library/tools/htmlhelp/wkshp/download_main.htm oldalról tölthető le. Nem véletlenül írtuk, hogy aktuálisan, mert ez bizony az időnkénti átszervezések miatt más oldalra is kerülhet. A cikk írásakor a fenti cím még létezett, ha mostanra ez már csak emlék lenne, akkor érdemes a Microsoft oldalain a keresést választani és ott a HTMLHelp szóra keresni. Valószínűsíthető, hogy néhány kattintás után már eljuthatunk a megfelelő oldalra.

Kezdjük Help Workshop használatával. A cikk készítésekor az 1.2 verziót használtuk. Ahhoz, hogy felhasználhassuk a súgó állományt, először is el kell készítenünk azt. Indítás után válasszuk a File New menüpontot. Ekkor megjelenik egy kis ablak, melyből azt választhatjuk ki, hogy mit is szeretnénk készíteni. Válasszuk most a Project elemet.

Ekkor elindul a New Project varázsló. Itt első kérdésében azt dönthetjük el, hogy egy régebbi Window Help-et szeretnénk-e konvertálni HTML Help-é. Mivel most újat szeretnénk létrehozni, így ezt ne válasszuk, hanem kattintsunk a Next gombra.

Második lépésben ki kell választanunk azt az alkönyvtárat, ahová menteni szeretnénk a készítendő HTML Help-et és a hozzá tartozó állományokat. A HTML Help forrás állománya, melyből készül a súgó HHP kiterjesztést fog kapni. A későbbiek folyamán, ha változtatni szeretnénk a help-en, akkor ezt az állományt kell megnyitnunk.
Ha ez is megvan, akkor ismét tovább léphetünk a Next-el.

Következő oldalon azt kérhetjük, hogy legyen-e tartalomjegyzék, index, stb. a help-hez. Most az egyszerűség kedvéért ezeket ne kérjük. A későbbiek folyamán természetesen még visszatérünk ezekre a lehetőségekre is.

Ismét a Next és ezzel készen is vagyunk már csak a Finish gomb lenyomására van szükség.

Ekkor megjelenik néhány új ablak, új nyomógombbal. A help készítéséhez szükségünk lesz néhány web lapra is, melyben bármilyen HTML kódot, java scriptet, minden egyebet felhasználhatunk, mint egy szokványos web lap készítésekor.

A help állományhoz új web lapot úgy tudunk hozzáadni, hogy a jobb oldalt látható függőleges nyomógomb sorból az Add/Remove topic files gombot választjuk. Ekkor egy listát kapunk, melyben felvehetünk új web lapot az Add gombbal, illetve törölhetünk már meglévőt a Remove gombbal.

Ha már van web lap felvéve, akkor a szintén jobb oldalon található gombok közül a Save all files and compile gomb lenyomásával elmenthetjük és lefordíthatjuk a forrást egy HTML Help állománnyá, melynek CHM kiterjesztése lesz.

Fordítás után kapunk egy ablakot, melyben a fordítás statisztikája és eredménye, valamint az esetleges hibaüzenetek láthatók. Ha nem volt gond, akkor létrejön a CHM állomány, melyre ha egy Intézőn keresztül rákattintunk, akár meg is nyithatjuk és láthatjuk a benne elhelyezett web lapot.

Ezek után be is zárhatjuk a HTML Help Workshop-ot és indítsuk el a Delphi-t, nézzük meg, hogy onnan milyen módszerrel érhető el az elkészült web lap.

A HTML Help valami oknál fogva még a Delphi 5-ös verziójában sem támogatott. Ez viszont nem jelenti azt, hogy ne tudnánk felhasználni, még akár a Delphi 3-as verziójából is.

A HTML Help kezelését a HHCtrl.ocx ActiveX objektum valósítja meg. Nincs más teendőnk, mit az ebben található HTMLHelpA függvényt meghívni a megfelelő paraméterekkel.

Első lépésként deklaráljuk a függvény típusát:
type
  THtmlHelpA=function(hwndCaller: THandle; pszFile: PChar; 
    uCommand: cardinal; dwData: longint): THandle; stdcall;
Majd ezt felhasználva létrehozunk egy globális változót:
var
  HtmlHelpA: THtmlHelpA;
Ennek a változónak értéket a unit inicializálásakor adunk. Itt a LoadLibrary függvény hívásával betöltjük a HHCtrl.ocx állományt. Ha ez sikerül, akkor a szintén globálisként deklarált OCXHandle változó nullától különböző értéket fog kapni. Ezt felhasználva a GetProcAddress segítségével már lekérdezhető a kérdéses függvény címe, melyet eltárolhatunk az előbb létrehozott változóba.
initialization
begin
  HtmlHelpA:=nil;
  OCXHandle:=LoadLibrary('HHCtrl.ocx');
  if OCXHandle0 then begin
    HtmlHelpA:=GetProcAddress(OCXHandle, 'HtmlHelpA');
  end;
end;
A betöltött állományt célszerű fel is szabadítanunk, mikor már nincs rá szükségünk, vagyis a program futásának végén. Ha a betöltés sikeres volt, vagyis az OCXHandle változó valós azonosítót tartalmaz, akkor a FreeLibrary hívásával ezt a felszabadítást megtehetjük.
finalization
begin
  if OCXHandle0 then begin
    FreeLibrary(OCXHandle);
  end;
end;
Ennyi előkészület után már bármikor meghívható a HTML Help függvénye, melyhez az egyszerűbb kezelés érdekében létrehozunk egy HTMLHelp nevű függvényt. Mivel a betöltés sikeressége attól függ, hogy a HTML Help, vagyis a HHCtrl.ocx állomány megtalálható-e, így a függvény hívása előtt ellenőrizni kell ezt.
function HtmlHelp(hwndCaller: THandle; pszFile: PChar; 
  uCommand: cardinal; dwData: longint): integer;
begin
  if Assigned(HtmlHelpA) then begin
    result:=HtmlHelpA(hwndCaller, pszFile, uCommand, dwData);
  end else begin
    result:=0;
  end;
end;
Így a függvényünk paramétereiben a következő értékeket kell megadnunk, amikor aktivizálni szeretnénk egy HTMLHelp állományt:
Első paramétere lesz annak az ablaknak az azonosítója (Handle), mely a hívást kezdeményezi. Ezután jöhet egy PChar típusú szövegként a CHM állomány, teljes elérési útvonallal.
Harmadik paramétere egy olyan konstans, mely az elvégzendő műveletre utal. Ehhez létrehozunk egy konstanst HH_DISPLAY_TOPIC névvel, mely arra utasítja a HTMLHelp-et, hogy jelenítse meg az adott fejezetet.
Az utolsó paraméterben egy egyedi 32 bites szám adatot adhatnánk meg, amelyre most nincs szükségünk. A későbbiek folyamán viszont még számtalan példát láthatunk ennek használatára is.

A függvény hívásával tehát megjelenik az imént készített első HTML Help súgó állományunk.

A további fejezetekben persze ennél jóval bonyolultabb példákat is készítünk még, melyeknek már több gyakorlati haszna lesz a mostaninál.

HTMLHelp cikksorozat