Using the HTML Help System


Currently, the most common Help system used in Windows applications is HTML Help, which uses CHM files. This system replaces the old Windows Help System (WinHelp), which used HLP files (see the sidebar, "Microsoft's Help System Evolution"). Both of these Help systems enable the developer to associate a context ID with a particular help topic. This makes it possible to display a particular help topic in a context-sensitive manner.

In this section, I briefly describe the HTML help-authoring system. Details on creating such Help systems are well beyond the scope of this book. However, you'll find lots of information and examples online.

Note  

If you plan to develop a large-scale Help system, I strongly recommend that you purchase a help-authoring software product to make your job easier. Help-authoring software makes it much easier to develop Help files because the software takes care of lots of the tedious details for you. Many products are available, including freeware, shareware, and commercial offerings.

image from book
Microsoft's Help System Evolution

Over the years , Microsoft has incorporated four different Help systems in its applications and operating systems:

  • WinHelp : Based on RTF ( rich-text formatting) files. This Help system was first used in Windows 3.0, 1990. Multiple RTF files are compiled into a single help file with an .hlp extension. Versions of Microsoft Office prior to Office 2000 use WinHelp.

  • HTML Help : Based on HTML (HyperText Markup Language) files. This Help system was first used in Internet Explorer 4.0, in 1997. Multiple HTML files are compiled into a single help file with a .chm extension. Office 2000 was the first version of Office to use HTML Help.

  • Microsoft Help 2 : Supports HTML, DHTML, XML, VBScript, and JavaScript. Multiple files are compiled into an .hsx file. This is the Help technology used in Office 2007. This help system is intended for large-scale applications.

  • Assistance Platform Help : AP Help is the help system used by Windows Vista. This help system may eventually be available for Windows XP.

image from book
 

A compiled HTML Help system transforms a series of HTML files into a compact Help system. Additionally, you can create a combined table of contents and index as well as use keywords for advanced hyperlinking capability. HTML Help can also use additional tools such as graphics files, ActiveX controls, scripting, and DHTML (Dynamic HTML). Figure 24-9 shows an example of a simple HTML Help System.

image from book
Figure 24-9: An example of HTML Help.
image from book
Displaying an Excel Help Topic

In some cases, you may want your VBA code to display a particular topic from Excel's Help system. For example, assume that you'd like to give the user the option to view Excel's Help system information on chart types.

First, you need to determine the Topic ID number of the topic. To do so, locate the topic in the Help system; then right-click and choose Copy Topic ID xxxx (where xxxx is the ID number for the topic). This shortcut menu command places the Topic ID on the Clipboard so you can paste it into your code. Next, just paste the copied number as the argument for the ShowHelp method:

 Application.Assistance.ShowHelp "HA01233737" 

Unfortunately, this statement works only if the user's Help system is set up to display local contents only (that is, the Help system is in Offline mode). If the Help system is in Online mode, the preceding statement displays the Help contents. I'm not aware of any way to check if the Help system is currently in Online or Offline mode.

Another option is to use the SearchHelp method, which does work when the Help system is in Online mode. Just supply a search term , and the user will see a list of matching Help topics. Here's an example:

 Application.Assistance.SearchHelp "format chart elements" 
image from book
 
CD-ROM  

A workbook that demonstrates this technique is available on the companion CD-ROM. The filename is html help\formletter.xlsm .

HTML Help is displayed by the HTML Help Viewer, which uses the layout engine of Internet Explorer. The information is displayed in a window, and the table of contents, index, and search tools are displayed in a separate pane. In addition, the help text can contain standard hyperlinks that display another topic or even a document on the Internet. It's also important that HTML Help can access files stored on a Web site. This is ideal for directing users to a source of up-to-date information that might not have been available when the Help system was created.

You need a special compiler to create an HTML Help System. The HTML Help Workshop, along with lots of additional information, is available free from the Microsoft Web site at this address:

 http://msdn.microsoft.com/library/default.asp?url=/library/en-us/htmlhelp/ html/vsconhh1start.asp 

Figure 24-10 shows the HTML Help Workshop with the project file that created the help system shown in Figure 24-9.

image from book
Figure 24-10: Using the HTML Help Workshop to create a help file.

Using the Help method to display HTML Help

Use the Help method of the Application object to display a Help file - either a WinHelp HLP file or an HTML Help CHM file. This method works even if the Help file doesn't have any context IDs defined.

The syntax for the Help method is as follows :

 Application.Help(helpFile, helpContextID) 

Both arguments are optional. If the name of the Help file is omitted, Excel's Help file is displayed. If the context ID argument is omitted, the specified Help file is displayed with the default topic.

The following example displays the default topic of myapp.chm , which is assumed to be in the same directory as the workbook that it's called from. Note that the second argument is omitted.

 Sub ShowHelpContents()     Application.Help ThisWorkbook.Path & "\myapp.chm" End Sub 

The following instruction displays the Help topic with a context ID of 1002 from an HTML Help file named myapp.chm :

 Application.Help ThisWorkbook.Path & "\myapp.chm", 1002 

Using an API function to display HTML help

The Application.Help method sometimes doesn't work reliably, so many Excel developers prefer to use an API function to display HTML Help. The API declaration is as follows:

 Private Declare Function HtmlHelp Lib "HHCtrl.ocx" Alias "HtmlHelpA" _   (ByVal hwndCaller As Long, ByVal pszFile As String, _   ByVal uCommand As Long, ByVal dwData As Long) As Long 

Here's a procedure that calls the HtmlHelp function and displays topic 1000. The function returns a value of 0 if the file is not found.

 Sub ShowHelp()     Dim Result As Long     Dim Topic As Long     Topic = 1000     Result = HtmlHelp(0, ThisWorkbook.Path & "\formletter.chm", &HF, Topic)     If Result = 0 Then MsgBox "Cannot display Help", vbCritical, APPNAME End Sub 



Excel 2007 Power Programming with VBA
Excel 2007 Power Programming with VBA (Mr. Spreadsheets Bookshelf)
ISBN: 0470044012
EAN: 2147483647
Year: 2007
Pages: 319

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net