CapeSoft.Com
Clarion Accessories
Ezhelp
Documentation
CapeSoft Logo

CapeSoft Ezhelp
Documentation

Download Latest Version FAQ History
Installed Version Latest Version

Introduction

After completing a major Clarion project thoughts naturally turned towards adding the usual Windows help. After a short investigation we decided that for most help requirements the standard Windows help format is simply too difficult to implement. Sure, there are great tools available to make it easier, but at the end of the day there are major amounts of overhead in terms of administration, synchronization and compiling.

We decided there had to be an easier way! A way that allowed you to do the minimum possible amount of overhead. A way that allowed you to spend your "help" time writing help - not managing it. Out of this need, Ezhelp was born.

We decided to implement the new look of Windows help - but at the same time make it possible to create and edit the help tips while your application is running. We also wanted the help to be more than just text so we added the ability to send messages back to your application, to run other programs, and to jump to any page on the Web by using the users installed browser.

We also made it absurdly simple to add Ezhelp to your existing application - because it's usually the last thing a developer thinks of. All the code is done in a couple of simple extension templates, and the developer has to do no hand-coding at all.

Ezhelp Features

Ezhelp will have the following visible effects on your Clarion application...

Ezhelp In Action
Ezhelp in action screenshot

Adding Ezhelp to an application

To add Ezhelp to an existing (or new) application, do the following.
OR:
There are a number of options you can set on each window, but they are mostly used for special cases. For most of the time the default choices will be fine for your use. If you get errors when you compile your app then have a look in the FAQ section for some possible problems and solutions.

For Multi-DLL applications, you need to add the ezHelp Global Extension to each application.

Viewing help when your application runs

To view a help tip when your application is running, do one of the following...

After you've just started using Ezhelp there will obviously be no tips entered, and you will see a message saying there is no help for that control. To see how to add, and format the help, read the next section.

Editing Tips at runtime

To edit the tips at runtime, you need to bring up the tip (using Right-Click What's This, F1 or the Question Mark icon) and then use the following hot-keys to do the necessary editing:

Alt-E - to edit the tip
Ezhelp editing tips screenshot

Alt-C - to format or configure the tip Editing Tips

To get to the first screen press Alt-E (for Edit) while viewing a tip. You will see a regular looking memo box which contains the tip for the text. Apart from typing in the actual text, this is where you can also place buttons, hyperlinks, web links, highlighted text, horizontal lines etc. Each of these items is discussed below.

Formatting or Configuring Tips

formatting or configuring tips screenshot

To get to the screen press Alt-C (for Control) while viewing the tip. You can then set the color and font of text, the actions for buttons, the destinations of links etc.

Important: To select the control you want to edit properties for, left click on the control so it becomes highlighted and then right click on the control to see the menu. When you have finished setting all the properties right click anywhere on the window to Save and Exit, or Cancel.

Note: Most of the following is demonstrated in the Ezhelp example application which is found in your Clarion/3rdParty/Examples folder. Note: If your application uses CHM files. See the information about calling CHM files from Ezhelp.

Note: It is not possible to edit tips that have been displayed as a Cue Card. To edit the tip use the Question Mark, or Right-Click method.

Note2: If the help window only contains an html / chm or URL link then hold down the CTRL key while Question Mark or Right-Clicking the button. This opens the help window instead of linking directly to your URL link. When viewing a tip there are two possible editing screens to go to. The first is where you edit the Content of the tip, and the second is where you edit the formatting, and properties of the content.

Deploying your application

In addition to the files that you normally ship with your application (i.e. without Ezhelp added), you need to ship:
  1. The ezHelp tips file (unless you want the user to create his own from scratch)
  2. If your application is compiled in Stand-alone mode, then you need to ship the Ezhelp DLLs with your application: c6Mshx.dll (for using an MSSQL tips file), c60HLPx.dll (for non-MSSQL based applications) and We60x.dll for Clarion6 applications. Replace 60 with 55 for Clarion5.5 and 70 for Clarion7 applications.

Support

Comments, suggestions and problems from all users are most welcome. You can contact us using one of the following methods.
CapeSoft Support
Support Page Find support page with various options here
Email
Telephone +27 21 715 4000
Fax +27 21 715 2535
Post PO Box 511, Plumstead, 7801, Cape Town, South Africa
CapeSoft Ezhelp may be purchased from: 
CapeSoft Sales
Web www.capesoft.com
Email sales at capesoft dot com
Telephone +27 21 715 4000
Fax +27 21 715 2535
Post PO Box 511, Plumstead, 7801, Cape Town, South Africa
Buy Online
Web Buy now at ClarionShop
www.clarionshop.com

Installation

To install Ezhelp simply run the supplied Installation file.

Examples

Ezhelp ships with example files, which not only demonstrate Ezhelp's functionality, but also are a useful resource to aid you in how to implement Ezhelp into your application.

These example applications can be found in your Clarion/3rdParty/Examples/Ezhelp folder.

Template Reference

Code :CallEzHelp

Purpose

Allows you to call the ezTip window directly. Use this template to call up the ezTip window using your own method, as opposed to the usual Question mark, and right click, methods.

Options

Procedure Name & Control Equate : The EzHelpTip window is usually called with the name of the calling procedure, and the equate of the control. This identifies which tip should be opened at this point.

Global Extension : EzhelpPrompt

Extension and control templates screenshot

Purpose

The built-in default for the text displayed when the user right-clicks on a control is "What's This". If you wish to set this default to something else then add the EzhelpPrompt extension template to the global extensions of your app.

Options

Tip Settings:
Disable Ezhelp in this application You can tell Ezhelp not to generate code into your application.
Default text for right-click Text for right-click popup menu. Defaults to '&What''s This?'
Use MS-SQL Ezhelp tip driver Check this option to make the tip file part of a MSSQL backend. You'll need to fill in the correct owner string to complete the connection:

Connection, Database, User, Password
Help file name This is the Ezhelp file that is used to store all the Ezhelp tips. Try something like 'Ezhelp.ezh'. (It's actually a TPS file)
Set edit level Controls the editing level that you want to allow in your application. Options included:
Allowed - Ezhelp tips can be edited using Alt-E and Alt-C
Command line - Editing only allowed with /EditTips command line.
No editing - Ezhelp tips can not be edited at run time.
Default Help Procedure name
(Not required)
(Optional) Use this where the control equate used below is not unique. Specify the procedure in which this control equate is found.
Default Help Control Name
(Not required)
(Optional) Leave blank if no default helptip is required. Specify a control name. You can provide any unique name if you do not wish to link to an existing control name.
Disable Ezhelp F1- Key If this is on the the F1 Key option to open the help will not be active.
Disable Right-Click If this is on then the Right-click menu option "What's this" will not be active.
MakeTip Stay Open If you check this checkbox the Window will not close when it loses focus or when the user clicks on it, only when the Esc key is press or, if used with the caption setting when the user clicks on the close button or uses the system menu to close the window.
Always on Top If you check this option the Tip will always stay on top of you application. i.e. if you have Tip Stay Open on, no matter what other windows open, your tips will always stay on top.
Make Tip variable width If you check this checkbox the Tip window will use a variable width and grow dynamically horizontally as well as vertically, to get a new line you will need to press the Enter key in the text box as the autowrapping will be off.

Note: You need to remove manual justification (i.e. line breaks) in your tip text to see the difference between this option being on or off.
Tip Window Caption You can give the Ezhelp tip a windows title bar, by specifying text here (no quotes needed). Leave blank for no windows title bar.
Tip Window Color You can specify the Tip background color by using a constant e.g. Color:Blue, 0FFEFEFH, 0DFFFFFH or 0FEFAF5H. Leave it blank for the default Yellow color.
Use your frame icon as the system icon Turn this on to set your system{prop:icon} to the same icon as the icon on your frame. This save you having to program the following.
Activate Cue Cards Turns on Cue Cards.
Various Cue Card Settings Allow you to set the delay for the Cue Cards, as well as which controls you want Cue Cards to work on.
Definitely Legacy Templates This is almost obsolete - in some older versions of Clarion, the template cannot detect whether your application is ABC or Legacy. Check this checkbox if your application is a legacy application.

Extension: EzhelpTips

Purpose

This template enables the usual Ezhelp functionality to your window. It puts the familiar Windows question mark at the top right corner of the screen, and enables a right-click popup menu for all the controls. It is the minimum template that you require on a window for Ezhelp functionality, and the only template that is required. The global template adds this template, with no options set, to all window functions.

Options

Popup text for this window : You can override the default popup text for this window here. The default is '&What''s This', or if you have used the Global Extension template ( Ezhelp Prompt) then the default is whatever you specified there.

Controls to exclude from right clicking : If you want a specific control NOT to get a popup menu when the user right clicks, then you can add that control to this list. Note that the Question mark method will still work.

Controls to Ignore : If you want a specific control NOT to get any Ezhelp help tip (or right click popup menu), then you can add that control to this list.

Disable Question mark:
If a specific Window takes some time to redraw then you can disable the Question Mark to help things along. Note: Ezhelp 1.1 and above have been optimized to counter this problem and this should only be used where there are a great many controls on a window.

Extension: ezWindow Event Handler

Purpose

One of the abilities of the ezTip window is passing an event back to your applications frame. This template allows you to simply handle this event by calling a procedure.

Options

Events to Handle : This is a list of the events you will receive, and which procedure must be called.

Cue Cards

Cue Cards are automatic help tips that appear if the user spends a long time on any particular field.

By default Cue Cards are NOT enabled. To enable Cue Cards go to the Ezhelp Global Extension, to the Cue Cards tab. Click the "Activate Cue Cards" option on.

You will also need to set the Delay ( around 800 - which is 8 seconds - seems about right ) and then select the controls which will be cued. We recommend you start by cueing just Entry controls ( this includes Entry, Text, Spin, Check and Radio controls ). If you want to you can also have cues on List boxes, and Buttons.

One more thing is highly recommended. Go to your Frame procedure, to the Ezhelp extension there. Go to the Cue Cards extension. There you will be able to select the Use Equate for the Help Menu, as well as an INI file name and INI Section.

The idea here is to allow your user to easily turn the Cue Cards on and off. Like most help features it can become very irritating if you are familiar with the package and help keeps intruding on you. So Ezhelp will automatically add an option to your main menu so they can turn the Cues on and off. The setting will be stored in the nominated INI file so that it is kept from one session to another.

IMPORTANT NOTE : In order for the Cue Cards to work properly your windows must be MDI windows. In other words the MDI attribute for the Window must be on. If the Cue Cards appear different on a particular screen, then this is a good first thing to check.

NOTE: Set the ini file (for storing the cue cards settings) in the ezHelp local extension on the frame procedure

Creating a default Help Tip file

New from version 1.7 of Ezhelp is the ability to prime an Ezhelp file with information that is already in your application. To do this do the following steps;


This will create a default tip file for your application. It will contain information taken from the MSG and TIP fields for your controls.

Ezhelp Tip Manager

From version 2.1 the Ezhelp Tip Manager has been removed. We will be updating this utility and possibly including it in future releases.

Function Reference

ezCallHelpTip (ApplicationName, ProcedureName, ControlName, ControlType)

Calls ezCallHelpTipEx

ezCallHelpTipEx (ApplicationName, ProcedureName, ControlName, ControlType, FEQ)

ezCallHelpTipEx (ApplicationName, ProcedureName, ControlName, ControlType, FEQ)

Parameters
Parameter Description
ProcedureName String
This is the name of the procedure doing the call.
ProcedureName String
This is the name of the procedure doing the call.
ControlName String
This is the name of the Control doing the call.
ControlType String
This is the Type of the control doing the call.
FEQ long
Returns

Nothing

Description

Calling this function causes the Ezhelp window to appear. The first four parameters identify the help screen that is being requested. If a help screen does not exist then a default help screen may be opened.

The order of opening screens is as follows:
  1. Screen identified by ApplicationName, ProcedureName and ControlName.
  2. If (1) doesn't exist then it looks for the screen identified by ControlName
  3. if (1) and (2) don't exist then it looks for a screen identified by ControlType

This allows you to create generic screens that work across a whole control name, or across a whole control type. For example you can set up a tip for the OK Button which will be called for all OK buttons that don't have specific help. You can also set up a tip for Button which will be called for all buttons which don't have specific help.

NOTE: There is no help available for items (generally) - if you have a control to display help for an ITEM, then select the controltyp as a BUTTON.

ezClose

ezClose( )

Parameters

None

Returns

Nothing

Description

This function undoes the actions done by the ezShowHelp function. It must be called before the window is closed, if the ezShowHelp function was called. Failure to call this function can result in undefined behavior.

ezSetPopUp

ezSetPopUp (GlobalPopUpString)

Parameter
Parameter Description
GlobalPopUpString String
Returns

Nothing

Description

This function allows you to set the global default for the right-click popup menu text. If this function is not used then the popup text will default to "What's This".

ezShowHelp

ezShowHelp (<Exclude>,< flag>)

Parameter
Parameter Description
Exclude String (optional)
This parameter allows you to exclude controls from getting a right-click menu. This parameter takes the form of a pipe delimited list containing a list of control equate numbers.
Flag Long (optional)
1 = disable question mark
2 = toolbar alerts
4 = disable cue cards here
Returns

Nothing

Description

This function initializes a window and prepares it for supporting Ezhelp. It activates the Question Mark button on a window (note that only windows that don't have a maximize button are allowed question mark buttons). It also alerts the right mouse click for all the controls not in the "exclude" list.

Note: This function should be called after the window is opened, before the Accept command.
Note: If you call this function then you must also call the ezClose() function before the window is closed. Failure to call the ezClose function can result in undefined behavior.

ezSetEdit

ezSetEdit (EditSetting)

Parameters
Parameter Description
EditSetting Byte
0 - Can Edit the Help Tip at runtime
1 - Can only edit the Help Tip if there is a command line parameter /EditTips
2 - Cannot edit the Help Tips at all even if the command line parameter is there.
Returns

Nothing

Purpose

This function allows you to programmatically turn runtime Help Tip editing off. Typically this would be used when you don't want the end user to be able to change any of the Help Tips. Remember that if you set it to 1 you can override it by setting a command line parameter /EditTips

Copyright

Ezhelp is copyright © 2021 by CapeSoft Software.
Each developer needs his own license to use Ezhelp. (Need to buy more licenses?)

Ezhelp is provided as is, and you use it at your own risk. CapeSoft Software and its employees accept no liability for anything lost because of Ezhelp. Use of this product implies acceptance of this condition.

You are authorized to distribute the DLL files free of charge. All other Ezhelp files are copyright CapeSoft Software and may not be distributed.

Frequently Asked Questions

Compile Errors Question Mark Issues Runtime Problems: Other Questions: 1) Question: When I compile Ezhelp I get an error when generating saying "Unknown Variable %AName".

    Answer: You have forgotten to add the Global Ezhelp extension template to your app.

2) Question: I am using PowerBrowse, and when compiling I get an error like "Unknown Identifier ?Fmt1:Order"

Answer: Some controls are defined on the PB screen, but not actually generated in the code. Go to the procedure in question and add the control which generated the error to the list of "IGNORED controls".

3) Question: I have added Ezhelp to a window with lots of controls. Now it won't compile because I get an ISL error.

Answer: this is because there are so many controls the compiler is having difficulty managing the Ezhelp call to all of them in one routine. The solution is to go to the screen with the problem and set the "Maximum Controls" per routine to say 10. If this doesn't help reduce it further to 5.

4) Question: I have installed Ezhelp on a screen, but the Question mark doesn't appear in the right hand corner.

Answer: Unfortunately Windows does not allow the question mark to appear on the same screen as a maximize or minimize button. On this screen your users will have to use the "right-click" method to see Ezhelp.

See Question 10 below.

5) Question: I don't have a maximize or minimize box, but I still don't get a question mark.

Answer: You must have the "System Menu" property for the window switched on for the question mark to appear. (This is a good idea anyway because pressing Alt-Minus on a screen without a System menu causes your program to crash).
The normal default icon is the clarion blue triangle. clarion blue triangle icon But you can change this 3 ways:

a) Use the "Use application frame icon as system icon" option in the "Appearance" tab under Global Extensions. This sets the application frame icon that you have specified as the default system icon for all the windows in your application.

b) You can change the Icon on the system menu by adding the following line to your Global Program Setup embed point :
system{prop:icon} = 'myicon.ico'
(Note you will need the myicon.ico in your application folder for this to work)

c) An improvement on (b) is to include an icon (for example myicon.ico) in your "library, object and resource files" section of your Project. And then add the following line to your Global Program Setup embed point :
system{prop:icon} = '~myicon.ico'

6) Question: You say I can post a message back to windows using the button. What does that mean?

Answer: It means you can post an "event" back to a thread number (normally the frame: 1). An user defined event is also called a user defined message.

7) Question: Exactly how do I set this up?

Answer: Go to your Main (frame) procedure extensions and insert the ezWindow Event Handler. Set this up to "watch" for a specific embed and to call a procedure when it is found. Then in your help you can post that event from a button to thread (1) and the procedure will start when that button is pressed.

8) Question: I am using Netscape and installed it with the standard install why won't it spawn my browser from an Internet Link?

Answer: It is tied to the registry and should pick up the default browser from "http" \ "https" entry in the Windows registry. Run regedit.exe and look under HKEY_CLASSES_ROOT\http\shell\open\command or HKEY_CLASSES_ROOT\https\shell\open\command, the entry should hold the path and exe of your browser. If you find it under another entry, like htmlfile please let us know and we will amend it.

9) Question: I read that you have a way of defaulting tips to certain buttons. What is it and where is it? How do I use it?

Answer: While editing the tip text you will notice you have three entry fields at the bottom of the window. ProcedureName, Control Name, Control Type.
1. If you omit the Procedure name for "AboutMyProgram, ?OK:Button, BUTTON" you will create a generic tip for ?OK:Button for all procedures

2. If you omit the Procedure Name and Control Name you will create a generic tip for all the control type BUTTON for all procedures.

When checking to see what tip to pop we first check "ProcedureName\controlName" then "ControlName" and lastly if it still couldn't find a tip we check "Control Type".

10) Question: The ? button on the titlebar does not appear when the window is opened. The ? only appears after the window is redrawn.

Answer: This is caused (in some cases) by using a DISPLAY command after the window OPEN command but before the window has actually appeared.
A solution is to move the DISPLAY command to the EVENT:OpenWindow embed point.

11) Question: What must I do in a Multi-DLL application?

Answer: You need to add the ezHelp global extension to each application (where it is required).

12) Question: I have an existing popup menu for my controls. How do I merge this functionality into ezHelp?

Answer: Add something like:

Mypopup.additem('-','ezseparator','',1)
Mypopup.additem('&What''s This','whatsthis','',1)
Mypopup.additemEvent('whatsthis',event:EzHelpWhatsThis,?MyField)


to your popup init (to add the 'whatsthis' item to your popup), and then in your ezHelpRoutine (to disable ezHelp's popup):

ezHelpRoutine Routine
  ezfield2 = 0
  case Field()
  of ?MyField     !Add a field here for each field that you want to override the ezHelp generic behaviour to.


13) When I click on the 'What's this?' item, then Ezhelp window doesn't show or does not receive focus.

Answer: Your window is set to modal. Modal windows hog the focus and stay on top, so modal windows aren't supported by ezHelp.

14) I can't Right-click on the control for <other 3rdparty product>.

Answer: You'll need to get hold of your other 3rdparty supplier and request a mod for their template in order to accommodate for the alerts that ezHelp requires. ezHelp generates alerts for each valid control in the ezShowHelp function (which is populated by the ezHelp template into your ThisWindow.Init method).

ezHelp uses the following code to alert the controls for the MouseRight click:

ControlID{prop:alrt,255} = mouseRight

I'm using visual indicators, but they don't show up when the screen opens.

Answer: You need to disable the question mark on that screen in order to view the visual indicators on window startup in that procedure. There's a bug in the Visual Indicators code that is affected by the API calls used by ezHelp in order to place the '?' button next to the Min and Max buttons.

Nothing happens when I try and execute a ScreenTip from the HelpButton.

Answer: You need to remove the STD:Help button type off the button.

When I press Alt-E and edit changes, it does not save my changes

Answer: If you would like to allow editing, you need to set this in the template. Also - if you are changing this at runtime (using the call to ezSetEdit) - then you must make sure that you set this before the call to the ezStayOpen function. Note: If you have a multi-dll application, then each application must have the same "Set edit level to" settings, otherwise you will get spurious results when trying to edit a tip. In other words, if you want your application to be set to command line, then set every application in the multi-dll to "Command Line".

15) I get a compile error: File not found: c6MSHx.lib

Answer: In order to make the Clarion6 project more Clarion7 friendly, we needed to change the name so that Clarion7 would change it automatically to the Clarion7 equivalent. The name changed from c6mshx.lib to c60mshx.lib. This means that the old lib is still included (now manually) in the project. You can simply delete both included lib files, and the template will add the correct one in automatically.

16) How can I display the ? for some users and the Max and Min buttons for others?

Answer: The best way would be to turn the Max and Min buttons on at runtime using the window's runtime properties - which you can set after the window opens:

If UserCondition
  0{prop:max} = true
  0{prop:icon} = '~MyIcon.ico'        !Include the icon required in the project.
end


This means that by default, the Ezhelp ? button will display unless these properties are set on an option selected by the user.

17) I try to remove EzHelp from my application by removing the global extension template, but it leaves behind the local extension template.

Answer:

This was an EzHelp issue that was fixed sometime back. Unfortunately the association (between the ezHelp local and global templates) is created when ezHelp is added to the application. So updating the template after the association was created in the template, won't create the association in your application. Hence deleting the EzHelp global template (without the association in your application) will leave the local extensions behind, even though you may be on the latest version of EzHelp.

Version History

Download latest version here

Version 3.20 (24 May 2021) Version 3.19 (13 September 2018) Version 3.18 (15 August 2018) Version 3.17 (12 December 2016) Version 3.15 (24 February 2015) Version 3.15 (24 February 2015) Version 3.14 (28 January 2015) Version 3.13 (20 January 2014) Version 3.12 (28 August 2013) Version 3.11 (24 April 2013) Version 3.10 (26 February 2013) Version 3.09 (21 April 2011) Version 3.08 (17 December 2010) Version 3.07 (6 December 2010) Version 3.06 (8 June 2010) Version 3.05 (4 June 2010) Version 3.04 (13 May 2010) Version 3.03 (11 May 2010) Version 3.02 (10 May 2010) Version 3.01 (29 December 2009) Version 3.00 (21 December 2009) Version 2.99 (9 April 2009) Version 2.98 (6 January 2009) Version 2.97 (25 November 2008) Version 2.96 (10 November 2008) Version 2.95 (14 September 2007) Version 2.94 (6 August 2007) Version 2.93 (6 July 2007) Version 2.92 (25 June 2007)
Version 2.90 (12 June 2006) Version 2.89 (6 June 2006) Version 2.88 (31 May 2006) Version 2.86 (14 April 2006) Version 2.85 (16 March 2006) Version 2.84 (12 January 2006) Version 2.83 (24 October 2005) Version 2.82 (5 October 2005) Version 2.81 (28 September 2005) Version 2.80 (27 September 2005) Version 2.79 (26 July 2005) Version 2.78 (15 December 2004) Version 2.77 (6 December 2004) Version 2.76 (25 November 2004) Version 2.75 (1 November 2004) Version 2.74 (21 September 2004) Version 2.73 (17 September 2004) Version 2.71 (29 July 2004) Version 2.70 (23 July 2004) Version 2.69 (16 April 2004) Version 2.68 (23 March 2004) Version 2.67 (5 March 2004) Version 2.66 (13 January 2004) Version 2.64 (11 December 2003) Version 2.63 (22 September 2003) Version 2.62 (28 August 2003) Version 2.61 (1 August 2003) Version 2.60 (31 July 2003) Version 2.59 (10 July 2003) Version 2.58 (26 June 2003) Version 2.57 (24 June 2003) Version 2.56 (19 June 2003) Version 2.55 (9 June 2003) Version 2.54 (6 May 2003) Version 2.53 (25 March 2003) Version 2.52 (24 March 2003) Version 2.51 (12 March 2003) Version 2.5 (26 Feb 2003) Version 2.0 / 2.1 Version 1.91 Version 1.9 Version 1.8 Version 1.7 Version 1.6 Version 1.5 Version 1.4