EZHelp v1.9 - by CapeSoft

by Tom Hebenstreit, Review Editor

Published 1998-07-01    Printer-friendly version

Help files.

The users demand them. You spend your time writing them. No one bothers to read them. But you have to do it, so you next have to decide which type of help to create. "Huh?" you say, "I thought help was help."

Well, there are really two types of help commonly used in Windows 95 (excluding the new HTML help format which Microsoft is now pushing). First, there are the standard, compiled files which are displayed by Winhelp.exe. An example of this type would the Clarion4 help provided by TopSpeed. The big drawbacks to this method are that it requires tools which can be quite expensive, you need a help compiler to produce usable files (at least that's free – if you can find it!), and it requires quite a bit of planning and coordination to ensure that your controls have Help IDs and that those IDs match up with the ones in the help file.

The second type is the context sensitive "What's this?" type of help which uses the question mark in the top right corner of many Windows screens to allow the user to point at various controls and pop up help for that specific control or option. The biggest drawback to this method for most Clarion users is that there is no way to implement it.

A final aspect of both of these methods is that the help text is basically 'etched in stone'. That is, it cannot be easily changed or updated without having all of the original tools, compilers, etc. By the way, these methods are not mutually exclusive; many applications use both styles when appropriate.

What to do, what to do…

Enter EzHelp, a collaboration between CapeSoft and Joe van Niekerk, which is designed to address quite a few of these issues. It aims to provide Clarion users with a simple, hassle free way of implementing the "What's this?" style of help, coupled with the ability to edit the help text on the fly, anytime, anywhere - no other tools (and no Help ID's) required.

Major Features

Note: I reviewed the Clarion4 version of ezHelp, since it was the most current version available when I began. During the review process, CapeSoft updated the CW 2.003 version to match the C4 version, so you can expect the same functionality from EzHelp for either version of Clarion. For C4, ezHelp supports both the Clarion and ABC template chains. As an aside, CapeSoft has also has ezHelp versions which are compatible with the C5 Enterprise Edition beta releases (registered users only).

Here's a rundown of the major features of ezHelp:

• Activates the Windows 95 "?" button, found on the upper right corner of a window's title bar, next to the "X" (close) button.
• Adds a "What's this?" item to right click menus, or creates the menu if no other right click options are defined.
• ezHelp screens can contains links to other ezHelp screens, links to World Wide Web pages, buttons to run other programs (include standard Winhelp), or even pass events back to your application.
• When moving through linked ezHelp screens, 'forward' and 'back' buttons are automatically provided.
• Help text can be created, edited and/or formatted directly from your application without the need for any additional tools such as word processors, help compilers or the like.
• Wizard and utility templates are provided which greatly simplify the process of adding ezHelp to your apps and creating the initial help file.
• All displayed text is under the control of the developer, allowing for easy internationalization.
• All help text is stored in a TopSpeed data file. Note that, even though ezHelp defaults to using an extension of EZH, it is still a standard TPS file.

Installation

I chose to download EzHelp from the CapeSoft web site, so I received the product as a password protected zip file. Within the zip was the actual EzHelp install program.

Performing the installation was a pretty painless process. The installer correctly located my Clarion4 directory and offered to install the templates there. It didn't offer to register the templates with C4, but did remind me to do so as the last step of the installation.

If anything, the EzHelp installer was a bit too enthusiastic for my taste, as it not only created a program group (which is good), it also added an EzHelp folder to my Desktop (which is cluttered enough already!). On the plus side, these do help to ensure that the beginner will find the EzHelp documentation, demo and utility program.

Implementation

Like any help system, there are really two parts to ezHelp:

First, there is the engine (the function library) that displays the help text. Hooking that up to my test apps was very easy – all I had to do was add the global extension and then run a utility which added an ezHelp template to every window procedure in the app (not reports, etc.). A quick recompile later, I had an application which had Windows 95 type question mark and right button "What's this?" help support. Very slick. If you are a glutton for punishment, you can also just go through your app and add the ezHelp procedure extension to any procedure yourself if that suits you (or your app) better.

In situations where you need finer control for a particular window, the ezHelp procedure extension template lets you specify individual controls in any given procedure that should either not respond to a right click, or not have any ezHelp at all. You can disable the display of the question mark button for that procedure as well.

The second (and by far the most time consuming) part of implementing any help system is, of course, creating the help text itself. To me, the truest measure of a help system is not what it does, but how easy (or hard) it makes the task of creating that text. EzHelp gives you a good head start on that task by providing a utility template that creates a basic help file using your app and, more important, the information you have entered into the message and tool tip fields for the various controls.

Once the file has been created, your next step is to run your application and fill in the help for each control. "Whoa", you say – "I have hundreds of controls in this app!" Not to fear… especially if you were careful to create good messages and tool tips before creating the default file. EzHelp also lets you create default help for all of your common controls such as OK, Cancel and Select buttons. For controls which have no tips or defaults, ezHelp provides a generic "No help for this Topic" message.

Figure 1: An update Form with an ezHelp window being displayed. Note the question mark in the top right hand corner of the Form

The process of creating and editing ezHelp text is accomplished via hot keys when the text is actually being displayed by ezHelp. For example, pressing Alt-E (for edit) while viewing the help for a button will shift ezHelp into edit mode, displaying the text for that button so that you can add to it, modify it, format it or whatever else it is you need to do.

If you want to get fancy in your help text, you can use what are basically web-style HTML tags in your text to add special features like buttons, horizontal lines, bullets, internet page links, or links to other ezHelp pages. Buttons can also be made to run external programs, post events back to your application, or even invoke a standard Windows help file. I must point out, though, that I discovered that the tags must be entered in upper case (a fact not mentioned in the documentation) or they will not be recognized. For example, to place a line on the help screen (also known as a Horizontal Rule), you must use <HR>, not <hr>. The first time I tried the latter, ezHelp interpreted it as a web page link (doh!).

Figure 2: The help window from Figure 1 in Edit mode. Note the HTML-like tags used to add the special characters and lines displayed in Figure 1

To help protect from having any old user mucking around in your carefully constructed ezHelp text, you can turn on an option whereby help editing is allowed only if a special command line parameter is used when starting the program. For total security, you can also simply disable all ezHelp editing from within your application.

An alternative method of creating your help text is to use the ezHelp Tips Manager utility program. After you select an ezHelp help file to work with, this utility displays, in tree fashion, a list of each procedure and the controls that they contain. As you click on the list entry for a given control, the raw help text is displayed.

I initially found this utility to be very confusing, since it appears that you would edit the displayed text directly via the insert, change and delete buttons as shown on the screen below. After some experimentation, it turned out that pressing Change (for example), would simply pop up the standard ezHelp display, which you would then edit the same way as always - by pressing Alt-E, etc.

Figure 3: The primary ezHelp Tips Manager window

The Tips Manager did turn out to be rather useful once I figured it out, because it lets you view all of the controls in your app without having to open, go through and close every screen to reach them. I must say, though, that this is one utility that would really benefit from having a few help screens of its own!

Performance

So how does one view ezHelp screens from within an application? By doing any of the following:

• Click on the "?" icon in the upper right corner of the window, which turns the cursor into a question mark. Whatever you click on with that cursor will pop up the help for that item.
• Right click on the item you are interested in and choose the "What's this?" option.
• Select the control you are interested in and press F1 (the help key).

Once I got the hang of how ezHelp worked, I found it very easy to view, edit and format the help text from within my application.

The only drawback I could see to ezHelp in average use was that window redraws seemed somewhat slower than normal when a help window was closed.

Documentation

Documentation is provided in the form of an HTML document (basically a Web page). As long as you have a web browser installed on your machine, you shouldn't have any problem reading or printing it. It can also be loaded into newer versions of Microsoft Word for Windows, or older versions that have the free Internet Assistant installed for Word. When printed, it turned out to be about 16 pages long.

The documentation includes sections on installation, implementation, Frequently Asked Questions (otherwise known as a FAQ), and reference guides for both the templates themselves and the underlying ezHelp function library. Finally, it includes a version history for the product as well as support information.

Overall, the quality was pretty good, but it could definitely use some documentation on the ezHelp Tips Manager as mentioned above. The step by step implementation section could also be updated to reflect the fact that a template it mentions is no longer needed by C4 (as stated in the template reference section).

The ezHelp Demo program is installed in an ezHelp directory under the C4 Examples directory. It serves as a good basic introduction to how the product will actually work once implemented in an application. The APP file for the demo is included as well.

Technical Support

Support is provided in the form of email, and responses from CapeSoft were typically very prompt. When I found a problem in the web links feature, CapeSoft worked with me to determine the cause and then provided me with a beta DLL to test the fix.

CapeSoft also provides phone and fax numbers for support, but seeing as how they are in South Africa and I am in California, I decided against trying them out…

Summary

EzHelp appears to be a good implementation of the "What's this?" style of help. It has a few minor rough edges, but those are more in the documentation and support utilities than the core product itself.

One area where it really shines is in creating a help file for smaller apps where the creation of a full-blown compiled Winhelp file may not be justified. Using ezHelp, I found I could create a reasonable help system in a remarkably short time.

All in all, I would definitely recommend ezHelp as worth a trial. Check it out!

Category	Product Score
Ability to do the task	Very Good
Ease of use	Very Good
Ease of Installation	Good
Documentation	Good
Technical Support	Very Good
Modifies Shipping Templates	No
Black-Box DLLs/LIBs	Yes

ezHelp v1.9 lists for $149 US, and is available through the TopSpeed Accessories program (call 1-800-354-544) or via CompuServe SWREG #13713.

For more information, shareware versions, demo programs, updates, news, etc., please visit the CapeSoft web site at http://www.capesoft.com.

Printer-friendly version

Copyright © 1999-2008 by CoveComm Inc. All Rights Reserved. Reproduction in any form without the express written consent of CoveComm Inc., except as described in the subscription agreement, is prohibited.

Clarion Magazine ISSN 1718-9942