HelpScribble: The Most Popular Help Authoring Tool Among Delphi & C++Builder Developers

HelpScribble's HelpContext Property Editor

One of the reasons why HelpScribble is popular among Delphi and C++Builder developers, is the way it integrates with those development tools. This integration is provided by the HelpContext property editor that is included with HelpScribble.

Adding context-sensitive help to the application you developed with Delphi or C++Builder can be a bit of a chore. No matter which help authoring tool you used, linking the appropriate help topics with the controls on your application's forms is done by assigning the topic mapping numbers from the help file to the HelpContext property of the corresponding controls. This is not a difficult task, but there are better ways to spend your time.

HelpScribble's HelpContext property editor makes linking up the help file with your application a snap. First you need to take a minute to install the property editor's package into Delphi or C++Builder. Then you can double-click on any HelpContext property in the Object Inspector to show the HelpContext property editor. On the left hand side of the property editor, you will see a tree of all the components on the current form. On the right hand side, you will see a list of all the topics in the current HelpScribble project. (HelpScribble must be running in the background.) To hook up a topic with a control, click on the control and then double-click on the topic's title. Easy! No longer will you need to mess around with those numeric Topic IDs.

HelpScribble's HelpContext property editor supports Win32 VCL development with Delphi 1 through 7 and C++Builder 1 through 6, VCL.NET development with Delphi 8, and both Win32 VCL and VCL.NET development with Delphi 2005, Delphi 2006 and C++Builder 2006. When Borland releases new versions of Delphi and C++Builder, a compatible version of the property editor will be released shortly thereafter.

You cannot use the property editor for WinForms development with Delphi 8, 2005 or 2006. You will need to use the method to link help files to .NET (WinForms) applications.

Adding the Help File to Your Application

In addition to setting HelpContext properties, you also need to tell Delphi which help file your application should use. This is done by setting the HelpFile property of the Application object. If you select Project|Options in Delphi, you can select the help file. Delphi then puts a line of code in your application's .dpr file.

Unfortunately, Delphi's Project|Options uses a literal string with the full path to specify the help file. Since the help file will likely be installed in a different folder on the user's computer, that won't work. It's better to use a line of code like this:

Application.HelpFile := ExtractFilePath(Application.ExeName) + 'myhelp.chm';

This line of code sets the help file to the file myhelp.chm in your application's installation folder. Note that in older versions of Delphi, modifying the HelpFile assignment in the .dpr file disables the Run button in the IDE. Put the line in your main form's OnCreate event handler instead.

Showing Help from Code

If you want to show help from code, such as an event handler for a menu item that should open the help file, call Application.HelpContext(1234) where 1234 is the Topic ID from HelpScribble of the topic that you want to open. This call works with both WinHelp and HTML Help.

The Application.HelpCommand() call only works with WinHelp. If your application has calls such as Application.HelpCommand(HELP_FINDER, 0) to show the table of contents for a WinHelp file, you'll need to change those to Application.HelpContext(10) when you switch to HTML Help, passing the Topic ID of the first topic in your help file.

Enabling the VCL Help System

The above two steps are the same for all versions of Delphi, and for both Win32 VCL and .NET VCL applications. The last step is different for various Delphi versions. Now that your application has context-sensitive help specified, and knows which help file to use, it also needs to know how to display help. Fortunately, this is as easy as adding the proper unit to your application.

Just Great Software is proud to be a CodeGear Technology Partner

Delphi 2006, 2007 and 2009

Delphi 2006 is the first version of Delphi that has built-in support for both WinHelp and HTML Help. Delphi 2006 also does not include any help support into your application by default. The same applies to Delphi 2007 and 2009. The move to Unicode in Delphi 2009 makes no difference.

Select Project|View Source in Delphi to open your application's .dpr file. If your help file is a WinHelp .hlp file, add the WinHelpViewer unit to the application's uses clause. Do so simply by typing in WinHelpViewer and the delimiting comma. Delphi will automatically find the unit.

If your application in an HTML Help .chm file, add the HTMLHelpViewer unit instead of the WinHelpViewer unit. You should not add both units to the same application.

In Delphi 2006 and 2007, both units are available in Win32 VCL applications and .NET VCL applications. Unlike .NET WinForms applications, .NET VCL applications can indeed use WinHelp files.

C++Builder 2006, 2007 and 2009

Like Delphi 2006, C++Builder 2006 and later don't include any help support in your application by default. You'll need to add either the WinHelpViewer or HTMLHelpViewer unit to your application. To do so, you'll need to add an #include and a #pragma line to the C++ code of your application's main form:

#include "HTMLHelpViewer.hpp" //------------------------------------ #pragma package(smart_init) #pragma link "HTMLHelpViewer" #pragma resource "*.dfm"

WinHelp with Older Delphi Versions

Delphi versions 1 through 8 have built-in support for WinHelp, which cannot be disabled. If your help file is a WinHelp .hlp file, you don't need to add any extra unit to your application.

Delphi 2005 also supports WinHelp out of the box, but does not automatically add WinHelp support to your application. Select Project|View Source in Delphi to open your application's .dpr file. If your help file is a WinHelp .hlp file, add the WinHelpViewer unit to the application's uses clause. Do so simply by typing in WinHelpViewer and the delimiting comma. Delphi 2005 will automatically find the unit.

HTML Help with Older Delphi Versions

Delphi versions 1 through 8, as well as Delphi 2005, do not support HTML Help for VCL applications. Fortunately, the free UseHTMLHelp and HTMLHelpViewer units that you can download make sure that Delphi knows how to use HTML Help. The archive contains three units, each for specific Delphi versions. UseHTMLHelp supports Delphi 3, 4 and 5. HTMLHelpViewer supports Delphi 6 and 7. HTMLHelpViewer2005 supports Delphi 2005.

Both UseHTMLHelp and HTMLHelpViewer were developed by Jan Goyvaerts, who also designed and developed HelpScribble. You may freely use these units in your software.

Delphi 3, 4 and 5

To enable HTML Help support in applications developed with Delphi 3, 4 or 5, add the UseHTMLHelp unit to your application. In Delphi, select Project|Add to Project in the menu, and select the UseHTMLHelp unit you downloaded using the link above.

HTML Help with Delphi 6 and 7

Delphi 6 has a totally new help architecture to enable an application to use more than one help system. Unfortunately, Borland did not make use of that architecture to support .chm help files. The HTMLHelpViewer.pas unit takes care of this. To add HTML Help support, use Project|Add to Project in Delphi to add the HTMLHelpViewer unit from the UseHTMLHelp download.

Unlike some other source code that is freely available on the Internet to make Delphi 6 work with HTML Help, the HTMLHelpViewer unit you can download here does not disable WinHelp. Should you use a .hlp file rather than a .chm file after all, HTMLHelpViewer will detect this and stay inactive, letting the standard WinHelpViewer do its job.

C++Builder 6

C++Builder 6 uses the same help system as Delphi 6. You can use the HTMLHelpViewer unit for Delphi 6 with C++Builder 6. You'll need to add an #include and a #pragma line to the C++ code of your application's main form:

#include "HTMLHelpViewer.hpp" //------------------------------------ #pragma package(smart_init) #pragma link "HTMLHelpViewer" #pragma resource "*.dfm"

You'll also need to link your application against hhctrl.ocx. First, run the command implib hhctrl.lib hhctrl.ocx. Then add the hhctrl.lib file to your project. The hhctrl.ocx file can be found in the Windows\System32 folder. It is included with Windows itself.

Using a HLP or CHM Help File with Delphi 2005

With Delphi 2005, Borland decided to change things once again. Delphi 2005 still uses the help system introduced with Delphi 6, but no longer adds a help viewer to your application by default. To make your application work with WinHelp .hlp files, add the unit WinHelpViewer to the uses clause of your project's .dpr file. This unit ships with Delphi itself.

To use .chm files, download the UseHTMLHelp package and add the HTMLHelpViewer2005 unit to your project's .dpr file.

If you want your application to support both .hlp and .chm help files, you must add HTMLHelpViewer to the .dpr uses clause before WinHelpViewer. Due to a bug in Delphi 2005, if you list WinHelpViewer first, WinHelpViewer will try to open .chm files, which will result in an error.

What About Kylix (Delphi for Linux) ?

HelpScribble is only available for Windows, but it does run fine under Linux if you use VMware or Win4Lin.

There is no standard help format on Linux like there is on Windows. Most Linux applications provide a bunch of HTML files as documentation. With HelpScribble's Project|Export to Web Help, you can easily create HTML files from your help project. If you do cross-platform development, you can use WinHelp files on Windows, and HTML files on Linux, all created from the same HelpScribble project.

If you use Borland Kylix, you can create an integrated help system based on HTML files using the Simple HTML HelpViewer package from Just Great Software.

If You Use Delphi or C++Builder,
You Need HelpScribble

Page URL: http://www.helpscribble.com/delphi-bcb.html
Page last updated: 17 May 2009
Site last updated: 22 June 2009