GUI ScreenIO for Windows

 ScreenIO.com


Using Microsoft HTML Help for Documentation

Microsoft currently recommends HTML Help as their standard documentation tool.  HTML Help allows you to distribute large documents as a single, compact file.  It also provides extensive indexing and full-text search capabilities. 

This GUI ScreenIO documentation was created using Microsoft FrontPage and Microsoft HTML Help. 

HTML Help is easy to use, plus you can download the HTML Help Workshop free from Microsoft.  

NOTE: Microsoft has released Security Patches which occasionally interfere with the operation of HTML Help.  These patches make html help fail when the html help file (.chm) is on a network drive.   We provide fixchm.txt and fixchm.reg in our GUI ScreenIO manual installer to get around this problem.  It will allow any .chm file to be invoked from a network drive.

Invoking HTML Help

When the user presses the F1 key, GUI ScreenIO will launch the standard Microsoft HTML Help application, open your compiled HTML Help (.chm) file, and attempt to locate the page for the panel currently being displayed.  It will also attempt to position the page to the entry for the currently active control.

You can also add Help entries to your application's menu to cause HTML Help to display the Table of Contents, the Index, or the Search tab when it is launched.

Multiple Language Support

GUI ScreenIO's help launcher will launch the help file for the language that is currently selected.  

Files used with HTML Help

HTML Help uses standard HTML files as input, plus several configuration files:

Creating HTML Help using GUI ScreenIO's Help Generator

Write your documentation

You define the text in the panel editor by right-clicking the item of interest, and selecting Edit Help... from the context menu.

The text for the Help Generator will be stored as a special entry in the comments of your panel copybook. 

Generate the HTML files

Close all of your panels, then select File/Help Generator from the panel editor's main menu.  Specify the locations for the source panel copybooks, and where you want the output files to be written.

Select MS HTML Help Input Files as the Output Format.

Choose how you will select the panels to be included in your documentation, then press the "Compile Selected" button.  This will create an HTML file for every panel you selected, that contains help text.  If you did not define any help text for an item, nothing will be generated for that item.

Last, press the "Generate Help" button. 

The GUI ScreenIO Help Generator will create the HTML Help project files automatically. 

Compile the HTML Help file

If you have installed the HTML Help Workshop, the Help Generator will launch the HTML Help Workshop after it has created the project files. 

Click on the grinder button in the HTML Help Workshop toolbar to compile your HTML Help file. 

This will produce a single (.chm) file that contains all of your documentation.  You can double-click this file to launch it, or you can run your application and let GUI ScreenIO launch your new HTML Help documentation when you request Help.

That's all - it's simple!

Creating custom HTML Help documentation

If your application requires more elaborate documentation than that provided by the automated Help Generator (for example, if you want to include images, tables, and other more complex objects in your documentation), you can manually create documentation in a way that can be integrated with GUI ScreenIO's help launcher.

If you choose to develop your documentation manually, you will still find it helpful to start by using the Help Generator to create the project files.  You can then modify them to suit your requirements.

We created this documentation using Microsoft FrontPage.  FrontPage creates HTML files which are used as part of the input to the HTML Help Workshop.

Integrating custom HTML Help with GUI ScreenIO

This section explains how to cause GUI ScreenIO to load the correct file and page when the user presses the F1 key.  If you use the Help Generator, this is done for you automatically.

Naming the .chm file for the correct language

The name of the HTML Help file must consist of the name of your main panel, and the suffix of the two-digit language ID that matches your alternate language IDs in your application.

For example, the English language version of this help file is GSEMAIN01.CHM.  The main panel of the panel editor is GSEMAIN, and the ID of the primary language - English - is 01. 

If the current language is English, GUI ScreenIO launches the Microsoft HTML Help application and specifies the filename GSEMAIN01.CHM.  If an alternate language were in use, it would specify the filename GSEMAINnn.CHM, where nn is the ID of the alternate language.

Naming HTML files so that they are loaded automatically

In order to have GUI ScreenIO automatically load the documentation page that applies to the current panel when the user presses the F1 key, the page must have the same name as the panel. 

So, if the panel is named MYPANEL, the HTML file for that panel must be named MYPANEL.HTM.

Note:  The panel names used in the generated HTML files include the language ID suffix in the HTML filenames, but your custom HTML Help files should NOT. 

That is, for language ID 01, the generated help will create HTML files named panel01.htm; for the second language, panel02.htm.  The runtime will pass the name of the panel with a suffix of the language ID when it attempts to locate the page for that panel in a generated HTML Help file.

When you specify that you are using custom help in your main panel's properties, the runtime does NOT concatenate the language ID to the panel when it attempts to locate the page for that panel.  We did this so that it is easier to translate HTML Help documents to other languages; the panel.htm filenames are the same across all languages. 

Specifying associative links to position to text for a control

If you wish to have the page automatically scrolled to the location of the text for the active control, you must define an associative link in the HTML document at that point.  If you use Microsoft FrontPage, you define a bookmark

You can also insert the link manually in your HTML, like this: 

<a name="FTnnnn">

where nnnn is the control's ID number. 

The easiest way to find the number of a control is to define some help for it, then use the Help Generator to create the HTML file for that panel.  Open the HTML file with a text editor and inspect it to find the link that is defined for the control of interest.

Generally, custom HTML Help would not contain many control-specific links, because it can be difficult to maintain them if you add or delete controls from the panels in your application.  If you need control-specific help, consider using the generated help.

Related topics:


© 2000-2019 Norcom, all rights reserved 

TOC

Send feedback to Norcom