Ubercode

Help for Programmers - Using the Help system

1. How do I call up Help for my programs?

There are several types of help file available to Windows programs. The following list gives some guidance on which to choose:

HLP file This is the original Windows help format, which supports embedded graphics, hot links, and copying / pasting of sample program code through macros. HLP files use a format proprietary to Microsoft and work with programs for all versions of Windows from 1995 onwards, but not with Windows Vista.
CHM file This format was introduced by Microsoft in 1996 and is intended as an eventual replacement for HLP files. It uses a mini web browser as the core of the display engine and is slower in operation compared to HLP files. CHM files require an installed web browser to operate correctly. Most help files in current use use the CHM format.
HTML file HTML as used on the internet is well suited for showing help information, although the help author has less control over the layout of the pages compared to other formats. HTML files require an installed web browser to operate correctly.
Vista help Microsoft Windows Vista will use a new form of help. Although Vista is now available, Microsoft have not yet defined this new format.

The best help format for Ubercode programs is either the HLP format or the CHM format - these formats offer the widest compatibility. The following example shows how to display a topic in a HLP file that is called "MyTopic". It assumes the file "myfile.hlp" is in the HLP format and has a topic called "MyTopic":

  call Winhelp(0, "myfile.hlp", HELP_KEY, "MyTopic")

The next example shows how to display the same topic in a CHM file. It assumes the file "myhelp.chm" is in the CHM format and contains a topic called "MyTopic", stored internally using an HTML file of the same name. Note this example has to construct the name of the internal HTML file that contains the topic:

  call Htmlhelp(0, "myfile.chm", HH_DISPLAY_TOPIC, "MyTopic" + ".html")

Next is shown how to display the same help page in an HTML file. This assumes "MyTopic.html" is a valid HTML file:

  var BrowserPath : string[*]
  ...
  BrowserPath <- RegGetBrowser()
  call Exec(BrowserPath, Dirstart()+"MyTopic.html", EXEC_NOWAIT+SW_SHOWNORMAL)

For more details on showing Help, refer to the Ubercode download and look at the Showhelp example. The example shows the most common help file tasks using different formats.

2. How do I create help using HTML?

The first step is to create an HTML file containing the help text. HTML can contain text, graphics and links, and in this example we create a simple HTML file with two topics:

  <html>
  <head>
  <title>My Help File</title>
  </head>
  <body>

  <h1>My Help File</h1>

  <h2><a name="topic1"></a>First Topic</h2>
  <p>This text is all about the first topic.</p>

  <h2><a name="topic2"></a>Second Topic</h2>
  <p>This text is all about the second topic.</p>

  </body>
  </html>

After the HTML file is created, save it as "myhelp.html" in the same folder where the program's EXE file is stored. Then add the following code to the program to display the help text from the HTML file:

  call Exec(RegGetBrowser(), 
            Dirstart()+"myhelp.html#topic1", 
            EXEC_NOWAIT+SW_SHOWNORMAL)

Note how the name of the HTML file is followed by a hash sign "#" and the topic name. To display the second topic, replace the file name with "myhelp.html#topic2". The HTML files are stored on disk so there is no limit to the number of files and the number of topics.

3. How do I integrate Help into a program?

Under Windows, the help system is displayed by using the winhelp.exe program to display a help file (*.HLP). You do not need to call winhelp.exe directly, since there is a Windows API function Winhelp which makes the correct calls to the winhelp.exe program. The Winhelp API function is also provided in the Ubercode run time library. The following details show how to use the help system for jumping to the contents page, showing a given page and other topics.

Show the help file contents page

When used: in response to the Help - Contents menu command from the main menu of a program.

Syntax: call Winhelp(0, Dirstart()+"myfile.hlp", HELP_KEY, "Contents") This assumes myfile.hlp is the HLP file which exists in the same directory as the main application EXE file, and it assumes the help file has a contents page with the topic identifier "Contents".

Show the help file index page

When used: in response to the Help - Index menu command from the main menu of a program.

Syntax: call Winhelp(0, Dirstart()+"myfile.hlp", HELP_PARTIALKEY, "") This assumes myfile.hlp is the HLP file which exists in the same directory as the main application EXE file. The HELP_PARTIALKEY option followed by an empty string causes the list of index phrases to be shown.

Show the "How to use help" page

When used: in response to the Help - Using Help menu command from the main menu of a program.

Syntax: call Exec("Winhelp.exe", "-h", EXEC_NOWAIT+SW_SHOWNORMAL) This runs the Windows Winhelp.exe program and makes it display its own page of help information, which describes how to use the help system.

Show a help page for one topic

When used: in response to any menu command that should display a single page of information, or in response to the Help button when clicked in a dialog box.

Syntax: call Winhelp(0, Dirstart()+"myfile.hlp", HELP_KEY, "Useful Dialog") This assumes myfile.hlp is the HLP file which exists in the same directory as the main application EXE file. The HELP_KEY option followed by a string tells the help system to go directly to the help file topic named "Useful Dialog". If there is no topic called "Useful Dialog" the help system displays a message to say it could not find the topic. This technique can be used to call up specific help pages, and to call up help pages that are customized for each dialog.

Show the "Help - About" dialog

When used: in response to the Help - About menu command from the main menu of a program.

Syntax: call AboutDialog("Help-About", Dirstart()+"logo.bmp", strPrompt, "OK") This assumes there is a file logo.bmp in the same folder as the application EXE file, and assumes the string strPrompt has been set up with the desired About box text.

4. How do I create a Windows Help File?

A Windows help file (HLP format) is created as follows:

First create an RTF file (rich text format file) containing the words, images and topics of the help file. An RTF file is simply an ASCII text file which uses special notation for different fonts and topic headings, and has the file extension ".rtf". A sample RTF file is available in the Ubercode help file under the topic "RTF file type".
Next prepare a simple HPJ file (help project file) which contains the list of files required for the help system. A simple HPJ file and RTF file can be created using the Ubercode helpster utility program.
Run the Microsoft help compiler (hcrtf.exe) on the HPJ file. All being well, this will create the HLP file.