Kompilierte Hilfedateien für das Zusatztool zum Excel WM Planer

Unser WM Planer wird langsam erwachsen und enthält mittlerweile zahlreiche Optionen und Features. Um unsere User bei der Bedienung des Planers und des späteren Zusatztool zu unterstützen, haben wir uns überlegt, dem Zusatztool eine kompilierte Hilfedatei im CHM-Format beizufügen. Aufgerufen wird die Hilfedatei über ein entsprechendes Symbol von der Hauptseite im Zusatztool.

Die Hilfedatei präsentiert sich dann wie folgend im Screenshot zu sehen. Wie sie sehen, das Layout unserer Website wird auch in der Hilfedatei integriert sein.

Klar, für moderne Anwendungen sollten eher Hilfedateien neueren Formats verwendet werden, wie sie beispielsweise von Visual Studio verwendet werden. Für den Planer sollte aber das ältere CHM-Format jedoch völlig ausreichend sein, zumal dieses Format auch von den neueren Windows Versionen unterstützt wird. Ausserdem lassen sich diese Dateien relativ einfach generieren und es gibt hierfür neben kommerziellen Anwendungen auch kostenlose Tools.

Ursprünglich hatten wir vorgehabt, für jede Sprache eine eigene Hilfedatei sowie eine dynamische CHM-Datei zu generieren, welche beim Aufruf eine passende Datei lädt. Leider lassen sich Unterpunkte in einer zur Laufzeit geladenen Hilfedatei nicht zuverlässig per Excel VBA ansprechen. Somit haben wir uns entschieden, alle verfügbaren Sprachen in einer Hilfedatei zu integrieren.

Um in Excel VBA die Hilfedateiladen zu können, bedarf es einiger API Importe aus dem für die Anzeige und Verwaltung zuständigen ActiveX Steuerelement „hhctrl.ocx“. Dieses muss dann natürlich auf dem System vorhanden sein und korrekt registriert worden sein. Es kann vorkommen, dass dies auf einigen System der Fall ist; Microsoft stellt jedoch hierfür Hotfixes bzw. Updates zur Verfügung.

Folgend der Code zur Schaltfläche im Dialog zum Excel WM Planer Zusatztool. Im Codemodul zur UserForm wird beim Anklicken der Schaltfläche die Funktion „mlfhHelp()“ aufgerufen, die sich in einem eigenen Modul befindet.

' Help... Private Function mlfhHelp() Dim lngTopic As Long Dim strPath As String Dim strFile As String ' Errors... On Error Resume Next ' Initialize... strPath = ThisWorkbook.Path strFile = Replace(ThisWorkbook.Name, "." & _ "xls", "." & "chm") ' Check... If Trim(UCase(Dir(strPath & "\" & strFile))) <> _ Trim(UCase(strFile)) Then mlfpMessage "MSG_HELP_LOAD" Else ' Current... lngTopic = CLng(CMB_0001_1001.List( _ CMB_0001_1001.ListIndex, 0)) ' Open... mlfpApiHelpLoad strPath & "\" & strFile, _ mlcpApiHelpContext, CStr(1000 * lngTopic) End If ' Result... mlfhHelp = 0 End Function

In der Funktion wird geprüft, ob die Datei an der dafür vorgesehen Stelle vorhanden ist, eine in einer Combobox versteckte ID ermittelt und an die Funktion „mlfpApiHelpLoad()“ übergeben.

Public Function mlfpApiHelpLoad(Filename As String, _ Action As Long, _ Data As String) As Long Dim typeQuery As mlthHelpQuery ' Bypass errors... On Error Resume Next ' Select... Select Case Action Case mlcpApiHelpTopic ' Call... mlvpApiHelp = apiHelpTopic(Application.Hwnd, _ Filename, Action, _ Data) Case mlcpApiHelpContext, _ mlcpApiHelpToc, _ mlcpApiHelpIndex ' Call... mlvpApiHelp = apiHelpHelp(Application.Hwnd, _ Filename, Action, _ CLng(Data)) Case mlcpApiHelpSearch ' Initialize... typeQuery.cbStruct = Len(typeQuery) typeQuery.fUniCodeStrings = 1& typeQuery.pszSearchQuery = Data typeQuery.iProximity = 0& typeQuery.fStemmedSearch = 0& typeQuery.fTitleOnly = 1& typeQuery.fExecute = 1& typeQuery.pszWindow = "" ' Call... apiHelpSearch 0&, Filename, _ mlcpApiHelpSearch, typeQuery Case Else End Select ' Return... mlfpApiHelpLoad = 0 End Function

Der Funktion wir der Dateiname inklusive Pfad, eine auszuführende Aktion sowie ein Datenblock übergeben. Je nach Aktion werden Elemente in der Hilfedatei, wie beispielsweise eine bestimmte Seite, eine Indexseite oder die Seite zum Suchen nach Inhalten angesprochen. Entsprechend kommen dann die API Importe „apiHelpTopic ()“, „apiHelpHelp()“ und „apiHelpSearch()“ zum Einsatz. Diese sind im Codemodul im Kopfbereich entsprechend definiert bzw. deklariert.

' ' Constants... ' ' ........................................................................ ' Display Public Const mlcpApiHelpContext As Long = &HF Public Const mlcpApiHelpTopic As Long = &H0 Public Const mlcpApiHelpToc As Long = &H1 Public Const mlcpApiHelpIndex As Long = &H2 Public Const mlcpApiHelpSearch As Long = &H3 ' ' Types... ' ' ........................................................................ Private Type mlthHelpQuery cbStruct As Long fUniCodeStrings As Long pszSearchQuery As String iProximity As Long fStemmedSearch As Long fTitleOnly As Long fExecute As Long pszWindow As String End Type ' ' API... ' ' ........................................................................ ' Help... Private Declare Function apiHelpHelp Lib "hhctrl.ocx" _ Alias "HtmlHelpA" (ByVal hwndCaller As Long, _ ByVal pszFile As String, _ ByVal uCommand As Long, _ ByVal dwData As Long) As Long Private Declare Function apiHelpTopic Lib "hhctrl.ocx" _ Alias "HtmlHelpA" (ByVal hwndCaller As Long, _ ByVal pszFile As String, _ ByVal uCommand As Long, _ ByVal dwData As String) As Long Private Declare Function apiHelpSearch Lib "hhctrl.ocx" _ Alias "HtmlHelpA" (ByVal hwndCaller As Long, _ ByVal pszFile As String, _ ByVal uCommand As Long, _ dwData As mlthHelpQuery) _ As Long ' User... Private Declare Function apiSendMessage Lib "user32" _ Alias "SendMessageA" (ByVal a As Long, _ ByVal b As Long, _ ByVal c As Long, _ d As Any) As Long

Ganz wichtig ist, dass bevor Excel geschlossen wird, die per Code geöffnete Hilfdatei auch zuvor geschlossen wird. Im schlimmsten Fall stürzt Ihnen ansonsten Windows (XP) mit einem Bluescreen oder Excel ab. Die Funktion „mlfpApiHelpClose()“ prüft ob das Hilfefenster noch vorhanden ist und, wenn ja, sendet eine Nachricht an dieses, um es zu schließen. Die Funktion wird dann aufgerufen, wenn das Zusatztool als solches geschlossen wird, also im Ereignis „Workbook_BeforeClose()“ oder wenn das Dialogfenster zum Tool geschlossen wird.

' Help... Public Function mlfpApiHelpClose() As Long ' Errors... On Error Resume Next ' Check... If apiHelpWindow(mlvpApiHelp) Then apiSendMessage mlvpApiHelp, &H10, 0, 0 End If ' Return... mlfpApiHelpClose = 0 End Function

Abschließend einige Links zu thematisch verwandten Seiten und Tools, die die Erstellung von CHM-Dateien vereinfachen und unterstützen.

• Excel WM Planer zur Fussballweltmeisterschaft 2010, Deutsch
• Microsoft HTML Help Workshop, kostenlos, Englisch
• Help Info, Portal mit umfangreichen Information zur Windows Hilfe, Deutsch
• CHM Decompiler, kostenlos, Englisch
• The Helpware Group mit kommerziellen Tools, Englisch
• Help & Manual mit kommerziellen Tools, Englisch
• HTML Help Smith mit kommerziellen Tools, Englisch