Home » Tutorials » Tools » HTML-Hilfe

HTML-Hilfe

What’s this

Viele Anwendungen haben in ihrer Kopf- oder Menüzeile einen Fragezeichen-Button, nach dessen Anklicken sich der Mauszeiger in ein Fragezeichen verwandelt.

Klickt man nun eine beliebige Komponente im Fenster an, erscheint ein kleines, gelbes Fenster mit einer kurzen Beschreibung. Das können wir natürlich auch in Delphi programmieren.

Das Fragezeichen-Icon

Um einen Fragezeichen-Button in die Fenstertitelzeile zu bekommen, wird im Objektinspektor unter BorderIcons biHelp auf true gesetzt. Das Fragezeichen wird zur Laufzeit jedoch nur angezeigt, wenn das Fenster nicht gleichzeitig auch noch einen Minimize- oder Maximize-Button enthält.
Bei Fenstern, die verkleiner- oder vergrößerbar sein sollen, ist ein Toolbutton nötig. Um daraufhin den Mauszeiger in ein Fragezeichen zu verwandeln, wird folgender Code verwendet:

procedure TForm1.WhatsThisToolButtonClick(Sender: TObject);
begin
  DefWindowProc(handle, WM_SYSCOMMAND, SC_CONTEXTHELP, 0);
end;

Erweiterung des Help Projects

Bevor wir auf diese Weise Hilfe-Popups anzeigen können, müssen wir unsere CHM-Datei erweitern:
Als erstes erstellen wir eine neue Textdatei, die alle Texte für Popup-Hilfen beinhalten soll:

.Topic IDH_POPUP_EDIT1
Dies ist ein Test-Popup.
;Kommentartexte beginnen mit einem Strichpunkt

.Topic IDH_POPUP_EDIT2
Dies ist noch ein Test-Popup.

Hinter .Topic steht die interne ID des anschließend folgenden Hilfetextes. Das kennen wir ja bereits. Wir speichern die Datei unter dem Namen „beispiel.txt“.
Ebenfalls nichts Neues ist die Zuordnung der alphanumerischen IDs zu numerischen. Diese schreiben wir in die Header-Datei, die wir bereits erstellt haben (beispiel.h):

#define IDH_POPUP_EDIT1  99
#define IDH_POPUP_EDIT2  100

Nun wechseln wir wieder in den HTML Help Workshop. Dort klicken wir auf der linken Seite auf den Button „HtmlHelp API information“. In dem nun erscheinenden Fenster wechseln wir auf die hinterste Seite „Text Pop-ups“ und fügen dort zuerst unser Header file (beispiel.h) und dann unser Text file (beispiel.txt) hinzu.

Anschließend muss die Hilfe neu kompiliert werden.

Einbau in unser Delphi-Programm

Unser Delphi-Code sieht im Prinzip aus, wie der im Verlauf dieses Tutorials erstellter (Erzeugung und Freigabe des Hooks). Jetzt müssen wir noch eine Prozedur hinzufügen, die das Design des Popup-Hinweises enthält. Gleich zu Beginn des implementation-Abschnitts kommt folgender Code:

{Alle 'Whats This' und F1 Help_ContextPopup WinHelp-Ereignisse werden
hier ankommen}
procedure F1HelpEvent(ContextHelpID: Longint; X, Y: Integer);
var hhpopup: HH.THHPopup;
begin
  with hhpopup do begin
    // Größe dieser Struktur
    cbStruct := SizeOf(hhpopup);

    // Instanz-Handle für String-Ressource
    hinst := 0;

    // Enthält 0, eine Ressourcen-ID oder eine Topic-ID in
    // einer Textdatei
    idString := ContextHelpID;

    // Enthält den Text, der angezeigt werden soll, wenn idString 0 ist
    pszText := nil;

    // top center (in Pixeln) des Popup-Fensters
    pt := Point(x,y);

    // Textfarbe, verwende -1 für Standard; RGB-Wert (hier rot)
    clrForeground := COLORREF($000000FF);

    // Hintergrundfarbe, verwende -1 für Standard; RGB-Wert
    clrBackground := COLORREF(-1);

    // Anzahl an Leerzeichen zwischen Fensterrand und Text, -1 für
    // jeden Teil zum  Ignorieren
    rcMargins  := Rect(-1,-1,-1,-1);

    // Schrift: facename, point size, char set, BOLD ITALIC UNDERLINE
    pszFont := '';
  end;
  HtmlHelp(Form1.Handle,
    PChar(ExtractFilePath(ParamStr(0))+'beispiel.chm::/beispiel.txt'),
    HH_DISPLAY_TEXT_POPUP, DWORD(@hhpopup));
end;

Was in der Prozedur eingestellt wird, ist durch die Kommentare erklärt. Wichtig ist die Zeile HtmlHelp ganz am Ende. Sie führt die eigentliche Aktion durch. Als erstes muss hier ein Fensterhandle stehen (in unserem Beispiel Form1.Handle; wenn das Fenster anders heißt, muss hier ein anderer Wert stehen). Der zweite Parameter ist der vollständige Pfad zur CHM-Datei gefolgt von ::/beispiel.txt, wobei beispiel.txt für den Namen der Textdatei steht, die die Popup-Texte enthält und die wir vorhin in unser Hilfeprojekt aufgenommen haben.
Direkt nach dem Erzeugen des Hooks im OnCreate-Ereignis muss diese Prozedur „aktiviert“ werden:

mHHelp.HelpCallback2 := F1HelpEvent;

Das Ergebnis unserer Mühe:

Wie die Kommentare in obigem Code schon angedeutet haben: Die Texte für Popup-Hilfefenster („What’s This“-Hilfe) müssen nicht in die CHM-Datei kompiliert werden. Es ist auch möglich eine String-Ressource anzulegen und diese direkt in die Delphi-Anwendung zu kompilieren. Ein Beispiel dazu findet sich unter dem Namen „example4“ auf der Download-Seite der Helpware Group.