HTML-Hilfe

Sobald eine Applikation eine bestimmte Komplexität erreicht hat, sollte für den Benutzer ein Hilfe oder sonstige Informationsquelle zugänglich sein.

B. Olaf Rasch 03/2003

 Anregungen oder Tipps an B. Olaf Rasch
 
Einführung voriges Thema [ Top ] nächstes Thema

Vielen VB-Einsteigern und selbst fortgeschrittenen Entwicklern fällt es jedoch schwer, sich dem mühevollen Generieren von .HLP- oder .CHM-Dateien zuzuwenden.
Hinsichtlich der Tatsache, dass heutzutage an nahezu jedem Arbeitsplatz ein Browser installiert ist, verwundert es nicht, dass immer mehr Softwarefirmen dazu übergehen, Beschreibungen und Hilfedateien ihrer Produkte im HTML-Format zu verfassen. Der ausschlaggebende Grund hierfür ist wohl die einfache Erzeugung dieser Dokumente und deren bequeme Abrufbarkeit sowohl lokal als auch über Intranet bzw. Internet.

Solche Dokumente können auch dem Programmierer in zweierlei Hinsicht dienlich sein:

 
 
 

Beim Erstellen während der Entwicklungsphase als allgemeine Orientierungshilfe, Erleichterung zum Ziehen von Zwischenbilanzen und Neuordnen von Projektstrategien,
Nach der Fertigstellung des Produktes als Nachschlagewerk und Grundlage für Handbücher, Spezifikationen und Schnittstellenbeschreibungen.

Im vorliegenden Projekt soll demonstriert werden, wie man einerseits solche HTML-Dateien innerhalb einer Anwendung anzeigen kann, und andererseits, wie sich ein kontextsensitiver Bezug zwischen Programmelementen und einzelnen Kapiteln einer Hilfedatei herstellen lässt.

 
Der Browser voriges Thema [ Top ] nächstes Thema

Analog zum Viewer für .CHM-Dateien wollen auch wir neben der eigentlichen Dokumentenanzeige ein TreeView-Control verwenden, um dem Benutzer einen Einblick in die Gesamtstruktur der Dokumentation zu verschaffen.

Somit gliedert sich die Form (frmHelpBrowse) in drei wesentliche Bereiche:

   Die Dokumenten-Übersicht (links),  
   das Anzeigefenster (rechts) und  
   das Menü (oben).
 

 

 
Dokumenten-Übersicht voriges Thema [ Top ] nächstes Thema

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 voriges Thema [ Top ] nächstes Thema
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
 
Die Steuerdatei (index.dat) voriges Thema [ Top ] nächstes Thema

Um die Html-Hilfe zu initialisieren, werden verschiedene Informationen benötigt:

  Aufbau der TreeView-Baumstruktur
  Knoten-Titel der einzelnen Elemente
 
  optional: HelpID's der einzelnen Elemente
 
  optional: Definition der zu verwendenden Icons
 
  optional: File-Namen der anzuzeigenden Dokumente
 
  optional: Name einer Startseite
 
  optional: Name einer Fehlermeldungs-Seite
 

All diese Informationen sind zentral in der Textdatei index.dat untergebracht, wo sie beim Aufruf der Sub Init ausgelesen werden, um die TreeView-Struktur des Browsers aufzubauen.

 
Aufbau eines Node-Eintrags voriges Thema [ Top ] nächstes Thema

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 voriges Thema [ Top ] nächstes Thema

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)

 
Download des Projekts voriges Thema [ Top ]   

Zum Abschluss können Sie sich hier das Projekt herunterladen

  Download
HTMLHelp.zip
 (58 kB)
Downloadzeit: <1 Min. - 28.8k / <1 Min. - ISDN Downloads bisher: [ 12632 ]

Startseite | VB/VBA-Tipps | Projekte | Tutorials | API-Referenz | Komponenten | Bücherecke | VB-/VBA-Forum | VB.Net-Forum | DirectX | DirectX-Forum | Foren-Archiv | VB.Net | Chat | Links | Suchen | Stichwortverzeichnis | Feedback | Impressum

Seite empfehlen Bug-Report

Letzte Aktualisierung: Sonntag, 23. März 2003