VB-fun.de - Tutorial016 (HTML-Hilfe)

Dokumenten-Übersicht

[ Top ]

Die Child-Knoten des TreeViews öffnen beim Anklicken bzw. beim Betätigen der Return-Taste ein entsprechendes Dokument, welches im Anzeigefenster erscheint. Als Images für die einzelnen Knoten sind neben den üblichen Icons auch noch ein paar zusätzliche Symbole verfügbar.

Icon	Key		Bedeutung
Root-Symbole
		books	Bibliothek / komplette Dokumentation
Ordner-Symbole
	book		Kapitel / Unterkapitel
	bookopen		(Bild für geöffneten Node)
	manual		Unterkapitel / Blattsammlung
	manopen		(Bild für geöffneten Node)
Dokument-Symbole
	sheet		Blatt eines Buches
	page		Blatt eines Manuals
zusätzliche Symbole
	info		allgemeine Informationen
	attention		wichtige Informationen / Warnung
	item		Unterpunkt / Anker

Diese Images decken in der Regel alle erforderlichen Bebilderungen für eine Hilfe-Struktur ab, du kannst jedoch ohne weiteres auch andere oder eigene Symbole verwenden, indem du neue Icons in die ImageList imlHelp einfügst.

Das Anzeigefenster ist durch ein WebBrowser-Control realisiert, so dass HTML-Dateien korrekt dargestellt werden können. Durch das PopUp-Menü des WebBrowsers kann der Benutzer navigieren, Text markieren/kopieren und die aktuelle Seite drucken, so wie er es vom Internet Explorer gewohnt ist.
Falls auf dem Zielrechner Word® oder Adobe Acrobat® installiert ist, werden im Anzeigefenster auch .DOC- bzw. .PDF-Dokumente mit Hilfe der vorhandenen Plug-Ins dargestellt.

Das Menü ist relativ einfach gehalten und hat folgenden Aufbau:

Browser	Allgemeines Dateimenü
	Beenden	Hilfe-Browser schließen
Ansicht	Visuelle Einstellungen für das Browserfenster
	Schriftgrad	Einstellen der Schriftgröße
		Sehr groß	(Schriftgrößen)
		Groß
		Mittel
		Klein
		Sehr klein

Um die Hilfe zu testen, benötigen wir eine Dummy-Applikation. Zu diesem Zweck habe ich einen minimalistischen Euro-Rechner geschrieben, mit dem man DM-Beträge jedoch auch in andere Währungen umrechnen kann.

Das Demoprojekt (Standard-EXE) umfasst folgende Module:

	eine Form (Name: frmMain),
	Dies ist das Hauptfenster, von welchem aus die Html-Hilfe aufgerufen wird. Es dient nur zu Demozwecken und enthält einen kleinen Währungsrechner.
	eine Dialogbox (Name: frmInfo),
	Diese Form wird gezeigt, wenn der Benutzer über das Menü den Punkt '? \| Info' wählt.
	die Browser-Form (Name: frmHelpBrowse) und
	Das eigentliche HtmlHelp-Fenster.
	ein Bas-Modul (Name: basHelpBrowse).
	Hier sind diverse Hilfsroutinen für den HelpBrowser untergebracht.

Implementierung

[ Top ]

Dateien

Um die Html-Hilfe in eigene Anwendungen einzubauen, werden 2 Dateien ins Projekt aufgenommen:

frmHelpBrowse.frm

basHelpBrowse.bas

Im Programm-Ordner müssen sich außerdem (evtl. in verschiedenen Unterordnern) die TreeView-Steuerdatei (index.dat) und die verwendeten HTML-Hilfedateien befinden.

Interface

Vor dem ersten Aufruf des Hilfefensters muss zur Laufzeit eine Initialisierung erfolgen, bei der verschiedene Parameter übergeben werden. Danach lassen sich im Code der Hauptapplikation gezielt die gewünschten Child-Knoten der Hilfe ansprechen.

Sub Init (TreeView-Struktur aufbauen)

ByVal index_path As String
(Ordner, in dem sich die Datei index.dat befindet, z.B. App.Path & "\doc")
ByVal root_path As String
(Ordner, in dem sich die Dokumente befinden, z.B. App.Path & "\doc\help")

Optional ByVal user_caption As String
(alternative Caption, die in der Titelzeile des Browsers angezeigt wird; hier könnte man den Namen der eigenen Anwendung anzeigen lassen, z.B. 'Print2001Plus-Hilfe')

Property GET InitOK (Mit dieser Eigenschaft lässt sich abfragen, ob die Initialisierung der HtmlHilfe mittels Init bereits stattgefunden hat bzw. erfolgreich war)

-> Boolean

Sub ShowTopic (Öffnet den Node mit dem Key id. Hat dieser Knoten Kinder, dann wird das Dokument des ersten Kindes angezeigt)

ByVal id As String
(Dieser Parameter entspricht normalerweise der WhatsThisHelpID-Eigenschaft eines Controls)

Naheliegenderweise benutzen wir die WhatsThisHelpID-Eigenschaft unserer Applikations-Elemente, um einen Einsprungspunkt in die Html-Hilfe zu erhalten.

Zum Aufruf der Hilfe verwende ich hierfür im Code der Eurorechner-Form die Sub CallHelp, welche dafür sorgt, dass die TreeView-Struktur aufgebaut wird, falls dies noch nicht geschehen ist.

Als Parameter übergeben wir noch das Flag use_id. Bei False wird das Hilfe-Fenster in seinem aktuellen Zustand angezeigt, bei True wird zusätzlich die WhatsThisHelpID des gerade aktiven Controls an die Hilfe weitergeleitet, damit die entsprechende Seite angezeigt wird.

Private Sub CallHelp(ByVal use_id As Boolean)
With frmHelpBrowse
    If (Not .InitOK) Then _
       .Init App.Path & "\doc", App.Path & "\doc"
    If (use_id) Then .ShowTopic ActiveControl.WhatsThisHelpID
   .WindowState = vbNormal
    .Show vbModeless
   End With
End Sub

Wenn nun der Benutzer die Hilfe über das Menü anwählt, rufen wir CallHelp mit False auf.

Private Sub mnuHH_Click()
CallHelp False
End Sub

Wird hingegen die F1-Taste gedrückt, dann ist eine kontextsensitive Hilfe erwünscht, und wir müssen das entsprechende Dokument für das aktive Control anzeigen lassen.

Die F1-Taste fangen wir im Form_KeyDown-Ereignis der Form ab (deren KeyPreview-Eigenschaft auf True gestellt sein sollte)

Private Sub Form_KeyDown(KeyCode As Integer, Shift As Integer)
If (KeyCode = vbKeyF1) Then 'F1-Taste abfangen
KeyCode = 0: CallHelp True
End If
End Sub

Aufbau eines Node-Eintrags

[ Top ]

Um die Eigenschaften eines Knotens zu definieren, werden diverse Angaben - durch Komma getrennt - in eine Zeile geschrieben.

Syntax: <Title>[,<HelpID>,<CloseIcon>,<OpenIcon>,<Document>]

Außer dem Titel sind alle Parameter optional; sollen z.B. nur Title und Document verwendet werden, müssen die Kommata für Title, HelpID, CloseIcon und OpenIcon gesetzt sein, damit der Document-Parameter als solcher identifiziert werden kann.

Die Bedeutung der Parameter im Detail:

Name	Bedeutung	Beispiel
Title	Anzuzeigender Knoten-Titel; wird in die .Text-Eigenschaft des Nodes eingetragen.	Die Druckfunktion
HelpID	Long-ID zum direkten Ansprechen eines Knotens. Normalerweise die WhatsThisHelpID-Eigenschaft eines Controls, auf das sich der Hilfe-Text bezieht; wird in die .Key-Eigenschaft des Nodes eingetragen (deshalb ist darauf zu achten, daß dieser Wert eindeutig ist, d.h. er darf nicht für mehr als einen Knoten eingetragen werden).	1002
CloseIcon	Key für das normale Node-Image. Dieser String korrespondiert mit der .Key-Eigenschaft eines Bildes der ImageList imlHelp (in frmBrowseHelp.frm).	sheet
OpenIcon	Key für das Image eines geöffneten (expanded) Nodes. Dieser String korrespondiert mit der .Key-Eigenschaft eines Bildes der ImageList imlHelp.	bookopen
Document	Name einer (in der Regel lokalen HTML-)Datei. Sobald man im TreeView ein kinderloses Element anklickt, wird der angegebene Dateiname mit dem RootPath ergänzt und an das WebBrowser-Control übergeben. Der RootPath ist der Basis-Ordner, in dem sich alle Hilfe-Dokumente befinden. Er wird dem HtmlHelp-Modul über die Sub Init (in frmBrowseHelp.frm) mitgeteilt. Der Document-String wird in die .Tag-Eigenschaft des Nodes eingetragen.	printdoc.htm
	Falls sich die Datei in einem Unterordner des RootPaths befindet, muss der Ordnername mit angegeben werden.	printhelp\printdoc.html
	Man kann RootPath-Unterordner auch im Document-Parameter von Parent-Knoten hinterlegen; die Dateinamen der Kinder beginnen dann mit einem Backslash ('\'), wenn sie von diesem Pfad Gebrauch machen.	\printdoc.html
	Bei HTML-Dateien ist auch die Verwendung von Ankern (Sprungziele innerhalb des Dokumententextes) erlaubt.	printdoc.html#paperbin
	Bei einer ausschließlichen Anker-Angabe wird der Name der zugehörigen HTML-Datei im Document-Parameter des Parent-Knotens erwartet.	#paperbin
	Externe Dokumente müssen mit http:// kenntlich gemacht werden.	http://www.vbpc.de
	Auch bei externen Dokumenten können Pfadangaben im Document-Parameter von Parent-Knoten hinterlegt werden; die Dateinamen der Kinder beginnen dann mit einem Slash ('/').	/printdoc.html

Die Ebene des jeweiligen Elements wird durch Kommata definiert, welche der Zeile vorangestellt werden. Beispiel für einen Buch-Knoten mit 2 Dokumenten plus SubFolder (Ordner 'Anhang'):

Kapitel 1,,book,bookopen
, Einleitung,,sheet,,einleit.html
, Adressenmaske,1043,sheet,,adrmask.html
, Anhang,,book,bookopen
, , Anhang A (Tabellen),,sheet,,anh_a.html
, , Anhang B (unterstützte Formate),,sheet,,anh_b.html

Hinweis: Wenn der Titel ein Komma enthält, muss er in Anführungszeichen gesetzt werden, damit das enthaltene Komma nicht als Separator fehlinterpretiert wird. Beispiel:

, , "Eingabe von Name, Adresse und Info",112,sheet,,input.html

Beispiel für den Zugriff auf externe Dokumente:

Interessante Seiten,,book,bookopen
, VBPC,,manual,manopen,www.vbpc.de
, , Home,,page,,/home.html
, , Source,,page,,/source.html
, , Mitgliederliste,,page,,/members.html
, , Newsletter-Archiv,,page,,/arv/index.html
, Microsoft,,manual,manopen,http://www.microsoft.com
, , Home,,page,,/ms.htm
, , Downloads,,page,,/downloads/search.asp?
, , Chat,,page,,http://webchat.msn.com

An Zusatzinformationen können noch die Namen von einer Startseite (DEFAULTDOC) und einer Fehlermeldungs-Seite (BROKENLINKDOC), welche im Falle einer nicht auffindbaren lokalen Datei gezeigt wird, angegeben werden. Beispiel:

DEFAULTDOC = welcome.html
BROKENLINKDOC = broken.html

So sieht übrigens die im Demoprojekt verwendete Steuerdatei aus:

;
; Projekt: HtmlHelpDemo
;
; Struktur der Baumansicht im Hilfe-Fenster
;

DEFAULTDOC = welcome.html
BROKENLINKDOC = broken.html

;###################################################### MENU START

Willkommen,,info,,welcome.html
HtmlHelpDemo Dokumentation,,books
;-----------------------------------------------------------
, Hilfesystem,,book,bookopen
, , Der Browser,,sheet,,browser.html
, , Die Steuerdatei,,sheet,,indexfile.html
, , Steuerdatei 'index.dat',,page,,index.dat
, , Implementierung,,sheet,,implement.html
;-----------------------------------------------------------
, Beispiel-Applikation,,book,bookopen
, , HtmlHelpDemo,,sheet,,appInfo.html
, , Menü,,manual,manopen,mnuMenu.html
, , , Menü: 'Datei',,page,,mnuMenu.html
, , , 'Beenden',,item,,#mnuDB
, , , Menü: '?' (Hilfe),,page,,#mnuH
, , , 'Hilfe',,item,,#mnuHH
, , , 'Info',,item,,#mnuHI
, , Euro-Rechner,,manual,manopen
, , , Euro-Rechner,,page,,eurocalc.html
, , , DM-Faktor,1000,item,,eurocalc.html#faktor
, , , Eingabe DM,1001,item,,eurocalc.html#dm
, , , Eingabe Euro,1002,item,,eurocalc.html#euro
;-----------------------------------------------------------

;######################################################## MENU END

Die komplette Anleitung zur Benutzung von HtmlHelp findest du übrigens auch im beigefügten Demoprojekt, wo sie Teil der angezeigten Hilfedokumentation ist.

Um mit dem Windows-CHM-Viewer konform zu bleiben, könnte man in den TreeView-Bereich ein TabStrip-Control mit 3 Registern setzen - eines wie gehabt für den TreeView (Inhalt), eines für eine Index-Seite (Liste mit allen relevanten Stichwörtern) und eines für eine Suchen-Seite.

Für die Stichwortliste müsste man zur Entwicklungszeit eine Tabelle mit allen wichtigen Begriffen und Verweisen auf die jeweiligen Dokumente erstellen; die Suchen-Funktion müsste alle die Hilfe betreffenden HTML-Seiten durchscannen und eine Trefferliste generieren können.

Diese Features zu realisieren ist zwar kein Hexenwerk, der Aufwand lohnt sich jedoch erst für Projekte, die um ein vielfaches umfangreicher sind als - wie in unserem Fall - ein simpler Eurorechner.

Falls auch nicht-lokale Dateien (die etwa auf einem Netzwerk- oder Internetserver liegen) eingebunden werden sollen, muss unter Umständen mit längeren Ladezeiten gerechnet werden, so dass der Benutzer mit Hilfe einer Fortschrittsanzeige darüber informiert werden sollte, dass etwas passiert.

Hier wäre es angebracht, z.B. in einer Statuszeile ein ProgressBar oder ein Prozent-Label unterzubringen. Im Code habe ich dafür im ProgressChange-Ereignis des WebBrowser-Controls schon Vorbereitungen getroffen; aus den übergebenen Parametern wird ein aktueller Prozentwert errechnet, der die Menge des übertragenen Datenvolumens widerspiegelt. Diesen Wert kannst du in geeigneter Weise für eine Fortschrittsanzeige verwenden.

Schlusswort

[ Top ]

Das verwendete WebBrowser-Control ist ein zu Unrecht stiefmütterlich behandeltes Werkzeug mit vielseitigen Einsatzmöglichkeiten. Als ich damit zum ersten Mal experimentierte, war ich zudem überrascht, wie einfach sich der Umgang mit ihm gestaltete.
Mit wenigen Code-Zeilen lässt sich bereits ein kleiner Internet-Browser entwickeln, der nahezu die gleichen Funktionen bietet, wie sein großer Bruder, der Internet Explorer. Kein Wunder, denn beide basieren auf der selben Library (SHDOCVW.DLL).
Abgesehen davon, dass man über die Navigate-Methode sowohl lokale als auch HTML-Dateien aus dem Internet laden kann, lassen sich - sofern die nötigen Plug-Ins vorhanden sind - eine Vielzahl von anderen Dateiobjekten in ein und demselben Fenster darstellen (TXT, PDF, DOC, JPG, GIF (auch animiert), BMP, ICO usw.).
Es lassen sich sogar Ordner übergeben, womit man den WebBrowser auch als Verzeichnis-Explorer in eigene Anwendungen einbauen kann.

Es lohnt also, sich einmal mit diesem Control zu befassen. Falls du nähere Informationen benötigst, dann empfehle ich folgende Seiten:
msdn.microsoft.com/workshop/.../.../WebBrowser.asp msdn.microsoft.com/workshop/.../.../reference/objects/WebBrowser.asp

All jenen, die HtmlHelp zwar für eine interessante Alternative halten, sich aber noch nicht näher mit HTML beschäftigt haben, möchte ich das umfassende und fundierte Tutorial/Nachschlagewerk SelfHtml von Stefan Münz ans Herz legen (frei downzuloaden unter www.teamone.de/selfaktuell). Hierin befinden sich ebenfalls Kapitel über Style-Sheets, JavaScript und CGI/PERL, die gerade für den Anfänger einen guten Einstieg in die Materie bieten.

Vielen mag es genügen, ihre HTML-Dokumente mit Word, Frontpage, Dreamweaver oder einem vergleichbaren Produkt zu erstellen. Der nicht von der Hand zu weisende Vorteil: Man benötigt keinerlei Kenntnisse von der HTML-Syntax.

Leider wird auf diese Weise aber fast immer eine nicht unerhebliche Menge an redundantem Code erzeugt, der die Dokumente unnötig aufbläht. Wer also HTML-Kenntnisse besitzt, wird seine Dateien vielleicht mit einem Texteditor nach bearbeiten oder sie gleich manuell (z.B. mit Notepad) herstellen.

Einen Kompromiss bieten sogenannte HTML-Editoren, welche dem Autor die Arbeit durch Syntax-Highlighting und Makrofunktionen wesentlich erleichtern. Für den semi-professionellen sowie professionellen Einsatz möchte ich hier das Freeware-Tool Phase 5 von Ulli Meybohm empfehlen (Download unter http://www.meybohm.de)