In this section:

1. Creating a help system
2. Help in ArcGIS Desktop applications
3. Invoking Compiled Help Files
4. Displaying help for your component

Creating a help system

Once you have developed new components for ArcGIS, you may want to provide documentation to help your users understand how to use the new functionality. The sections below will help you to understand how help is provided in ArcGIS and how you can provide help for your own components.

Help in ArcGIS Desktop applications

ArcGIS Desktop applications such as ArcCatalog, ArcMap, and ArcScene, provide online user assistance in six contexts.

• ArcGIS Desktop Help, accessed by the Help menu or the F1 key.
  
• Context-sensitive help for commands or tools, shown by using the What's This tool or using the Shift+F1 key combination when a particular item is highlighted.
  
• Context-sensitive help for controls on dialog boxes or on property pages, and also buttons in dialog boxes or property pages that display more extensive help topics.
  
• ArcGIS Developer Help, invoked from the Start menu.
  
• Context-sensitive help for object model components, contained in the ArcGIS Developer Help, invoked from the Visual Basic for Applications IDE.
  

Although you cannot merge your own help file with the ArcGIS Desktop Help or the ArcGIS Developer Help, you can supplement the ESRI-provided help with your own help in all of the situations listed above.

Invoking Compiled Help Files

ArcGIS uses compiled Help files in both WinHelp (.hlp) and HtmlHelp (.chm) formats.

HtmlHelp is used for the majority of help in ArcGIS—for example, both ArcGIS Desktop Help and the ArcGIS Developer Help are HtmlHelp systems. WinHelp is used as a supplementary system for context-sensitive help, as it is able to display formatted text and diagrams in lightweight windows.

HtmlHelp is used for most ArcGIS Help files.
WinHelp is used to provide 'What's This' help in the UI.

In many of the examples below, both formats are used to show the varying syntax and use. However, you need only use the format that best meets your needs.

First, you should review the basic mechanism used to display HtmlHelp and WinHelp—these basics are common to all situations where you may want to display a help window.

Displaying HtmlHelp in VB

1. Write and compile your HtmlHelp file—you can either use the Html Help Workshop tool, which is part of Visual Studio 6.0, or any third party HtmlHelp tool.
2. Add an entry to the Windows registry to indicate the path of the Help file. ESRI's practice is to register HtmlHelp Help files on installation in

   HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\HTML Help

   You can also register your help files to this location if you want. If you do not register your help files, you can alternatively pass in the full filename and path when you call the Help display function.

3. The HtmlHelp function in the Hhctrl.ocx library is used for all interaction with HtmlHelp. Add the following Win32 API declaration for this function to a module if working in VB 6.
   [Visual Basic 6]

   Declare Function HtmlHelp Lib "hhctrl.ocx" Alias "HtmlHelpA" ( _
    ByVal hwndCaller As Long, ByVal pszFile As String, _
    ByVal uCommand As Long, ByVal dwData As Long) As Long

4. Add a declaration for the HH_DISPLAY_TOPIC constant, which informs the HtmlHelp function that it should display a Help window.
   [Visual Basic 6]

   Public Const HH_DISPLAY_TOPIC = &H0

5. Use code similar to that below to call the HtmlHelp function, passing in the window handle of the current application (hWnd), which is the filename of your help file, the HH_DISPLAY_TOPIC constant.
   [Visual Basic 6]

   Dim hwndHelp As Long
   hwndHelp = HtmlHelp(hWnd, "MyHelpfile.chm::\IntroPage.htm", ;HH_DISPLAY_TOPIC, 0)

   This code will display the page called "IntroPage.htm".

   Note that no path is specified for the .chm file. The value returned from the function call is the window handle of the new HtmlHelp window you just created.

Use the Win32 call HtmlHelp to display a HtmlHelp window.
You can also use this API call to open a specific topic in a help file and to execute various other HtmlHelp commands.

Displaying HTML Help in VC++

In VC++ you use the same HtmlHelp function as described previously for VB. The HtmlHelp header file and library you will need to use can be found under the HtmlHelp Workshop installation folder.

1. Begin by compiling and registering the Help file, as described in steps 1 and 2 for VB.
2. Include the WinHelp.h header file in your own header file.
   [Visual C++]

   #include <htmlhelp.h>

   VC++ users can find the Htmlhelp.h header file as part of the HtmlHelp Workshop installation.

3. Link to the HtmlHelp.lib import library.
4. Use code similar to that below to call the HtmlHelp function—the code assumes that hWnd points to the handle of the currently active window, and filePath contains the filename of your help file and the topic you want to display. HH_DISPLAY_TOPIC is defined in HtmlHelp.h.
   [Visual C++]

   ::HtmlHelp(hWnd, filePath,HH_DISPLAY_TOPIC, 0);

Displaying WinHelp in VB

WinHelp is displayed in a similar way to HTML Help.

1. Write and compile your WinHelp file—you can either use the Help Workshop tool that is part of Visual Studio or any third-party WinHelp tool.
2. Add an entry to the Windows registry to indicate the path of the help file. ESRI's practice is to register WinHelp files on installation in

   HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\HELP

   You can also register your help files to this location if you want. If you do not register your help files, you can alternatively pass in the full filename and path when you call the Help display function.

3. The WinHelp function in the Windows User32 library is used for all interaction with WinHelp. Add the following API declaration to a module if working in VB 6.
   [Visual Basic 6]

   Public Declare Function WinHelp Lib "user32" Alias "WinHelpA" ( _
    ByVal hwnd As Long, ByVal lpHelpFile As String, _
    ByVal wCommand As Long, ByVal dwData As Long) As Long

4. Add a declaration for the HELP_CONTEXT constant—this informs the WinHelp function that it should open a particular topic.
   [Visual Basic 6]

   Public Const HELP_CONTEXT = &H1

   Use the WinHelp Windows API call to open a WinHelp window, specifying a particular topic ID if required. WinHelp topic IDs are compiled into the WinHelp file by Help Workshop.

5. Use code similar to that below to call the WinHelp function, passing in the window handle of the current application (hWnd), the filename of your help file, the HELP_CONTEXT constant, and the Help Context ID of the page you want to display.
   [Visual Basic 6]

   Dim lResult As Long
   lResult = WinHelp(Me.hwnd, "MyHelpfile.hlp", HELP_CONTEXT, 100)

   The WinHelp function performs essentially the same task as the HtmlHelp function. However, rather than the name of an HTML page, WinHelp requires that you pass the topic ID's mapped numeric value.

   The topic ID is the so-called # footnote in the RTF file you include in your WinHelp file. You can use Help Workshop to add this numeric value by opening the HPJ file, clicking Map, then clicking Add (to add the mapping for an individual topic). See the Help topic "To enable a program to display an individual Help topic" in the Help Workshop's Help file.

   The value returned from the function call is the window handle of the new HtmlHelp window you just created.

Displaying WinHelp in VC++

Calls to WinHelp are straightforward in VC++, as they are part of the Windows API.

As the WinHelp API call is part of the Windows API, VC++ programmers can call the function directly.

1. Begin by compiling and registering the Help file, as described in steps 1 and 2 for VB.
2. Use code similar to that below to call the WinHelp function—the code assumes that hWnd is the handle of the currently active window, filePath points to a string that contains the filename of your help file, and helpId is a double word containing the topic ID of the topic you want to display.
   [Visual C++]

   ::WinHelp(hWnd, filePath, HELP_CONTEXT, helpId);

Filepaths

No filepath is specified in either of the examples above—as the help filenames and paths were added to the registry, the HtmlHelp and WinHelp functions are able to locate the installed path of the files.

Alternatively, you can specify the full path to the help file in either the HtmlHelp or WinHelp functions.

HtmlHelp hWnd, "C:\Program Files\ABC\MyHelpfile.chm", HH_DISPLAY_TOPIC, 0)
WinHelp(Me.hwnd, "C:\Program Files\ABC\MyHelpfile.hlp", HELP_CONTEXT, 10)

By adding help file information to the windows registry, you can open help files without having to know the pathnames of the files.

The method you choose to use depends on your requirements. If you create an installation program for your component, it may be simpler to write the registry values during the installation than working out the path at run time in your component.

Displaying help for your component

Below is more information on the various places you may want to provide access to help.

Invoking help from ArcGIS applications

As you cannot merge your own help file with the ArcGIS Desktop Help, you can instead add a command that invokes your compiled help file to the Help menu of an application.

You can add a command to the ArcGIS UI to open your main help file.

First, create a class that implements ICommand. Then in its OnClick method, invoke your help file by calling the HtmlHelp (or WinHelp) functions, as described previously. Add this command to the application's Help menu.

Invoking help from a standalone application

If you are creating a standalone application, you can also use the code shown previously to invoke help files from menu items or buttons when your application requires it.

Help files can be invoked from standalone applications. To conform with Windows standards, ensure any Help windows opened by your application are closed when the application exits.

To be consistent with other applications, a user would expect that exiting your application would also close any Help windows that were created either directly or indirectly by your application. To close any HtmlHelp windows that were opened by your program, the HtmlHelp function can be called using the HH_CLOSE_ALL constant. In VB, you would use this in the QueryUnload method of a VB form.

Private Const HH_CLOSE_ALL = &H12
 
Private Sub Form_QueryUnload(Cancel As Integer, UnloadMode As Integer)
  HtmlHelp hWnd, "", HH_CLOSE_ALL, 0&
End Sub

More information on closing all HtmlHelp windows can be found on the Web sites listed below, particularly the Helpware Web site.

To close a WinHelp window opened by your program, use the HELP_QUIT constant, passing in the name of the WinHelp file, as shown below in VB.

Public Const HELP_QUIT = &H2
...
WinHelp Me.hwnd, "MyHelpfile.hlp", HELP_QUIT, 0

If you opened more than one WinHelp file during execution, you should quit each file individually.

There are several newsgroups and Web sites devoted to tips and techniques. The Web sites listed below are notable parts of an active help user community and provide excellent reference material for developers.

• Microsoft Help authoring newsgroup:
  Microsoft.public.helpauthoring
• Helpware Web site:
  http://www.helpware.net
• Help Technology Centre Web site:
  http://www.mvps.org/htmlhelpcenter

There are several newsgroups and Web sites you may want to go to for more indepth information on creating and calling help systems.

Displaying help for dialog boxes and property pages

In ArcGIS, there is sometimes the requirement to provide help for a certain command or wizard, more than a simple ToolTip—it may contain many paragraphs of text and, therefore, require a scrollable window, or it may include diagrams or hyperlinks.

In ArcGIS, a secondary window is used for this type of help page; a secondary window, unlike a main window, does not have a menu bar. For example, the GeoProcessing wizard shown here includes a button to explain more about the process that is selected in the wizard.

Secondary Help windows are often used to display certain topics when you do not wish to open a full help file. Both WinHelp and HtmlHelp topics can be opened as secondary windows.

You can use either the WinHelp or HtmlHelp functions to display a WinHelp or HtmlHelp window as you did before. For example, to display a specific page in HtmlHelp, use the HELP_CONTEXT topic and pass in the name of the page you want to display for the current state of the dialog box.

To specify that a WinHelp page should display in a secondary window instead of the main Help window, add a greater than sign (>) and the name of the secondary window to the end of the help filename.

lResult = WinHelp(Me.hwnd, "MyHelpfile.hlp>DialogHelp", HELP_CONTEXT, 10)

You can use similar syntax with the HtmlHelp function.

hwndHelp = HtmlHelp(hWnd, "MyHelpfile.chm::\IntroHelpPage.htm>DialogHelp", _
 HH_DISPLAY_TOPIC, 0)

In both of the cases above, the named secondary window should be defined in the HtmlHelp project or WinHelp project, respectively. You can use Help Workshop or HtmlHelp Workshop to define the name of the window and its appearance (color, size and initial position, and window title).

What's This Help for Commands and Tools

In an ArcGIS application, a user can display What's This help for a command or tool in two ways.

• By selecting the What's This tool and clicking another command or tool.
• By highlighting a command or tool and pressing Shift+F1

'What's This' help windows are opened from the What's This tool in the ArcGIS UI or by pressing Shift+F1. These are lightweight windows with no menu, scrollbars, or frame.

What's This help is displayed in a popup window—this is a lightweight window that does not have a menu bar, menu, frame, or scrollbar. It disappears upon any subsequent mouse click or key press.

The HelpFile and HelpContextID properties of ICommand are used to link a custom command to the What's This help in the ArcGIS applications.

Using WinHelp for What's This help for a command

ArcGIS applications use WinHelp files to display What's This help, as WinHelp supports formatted text and graphics for popup windows. The example code below for ICommand demonstrates calling WinHelp for What's This help for a custom command.

Private Property Get ICommand_HelpFile() As String
  ICommand_HelpFile = "MyHelp.hlp"
End Property
 
Private Property Get ICommand_HelpContextID() As Long
  ICommand_HelpContextID =  1234
End Property

What's This help for a command is opened automatically if you have correctly specified the ICommand members HelpFile and HelpContextID.

Topics can be linked to an ID number either directly in Help Workshop or by using a text file listing topic name and ID number. The actual contents of each topic should be included in an RTF file, which is compiled into the Help file.

Using HtmlHelp for What's This help for a command

It is also possible to specify an HtmlHelp topic for What's This help for a command, if required. Note that HtmlHelp does not support formatted text or pictures for popup windows. For the ICommand::Helpfile property, specify the name of the HtmlHelp .chm file.

Private Property Get ICommand_HelpFile() As String
  ICommand_HelpFile = "MyHelp.chm"
End Property

WinHelp What's This help windows support the addition of formatted text and graphics—HtmlHelp What's This help windows do not support either.

Generally calling HtmlHelp, you would specify a topic name—however, for the HelpContextID property, you must pass a symbolic ID number. Symbolic ID numbers should be defined in a header file in your HtmlHelp project, along with the topics to which they relate.

The actual contents of the popup windows should be specified in a text file; see the HtmlHelp Workshop's online reference for information on creating popup topics.

If you require more information about the Helpfile and HelpContextID properties of ICommand, refer to the ArcGIS Developer Help.

Displaying context-sensitive help for controls on a property page

Many of the property pages in the ArcGIS Desktop applications have context-sensitive help for individual controls on these property pages. Popup help topics appear when the control has focus and the user presses F1 or selects the What's This menu button and clicks a control.

You can provide context-sensitive popup help for your own property pages by linking the controls on your property page dialog box or form to ID numbers specified in your help file.

The IComPropertyPage and IComPropertyPage2 interfaces contain two properties, HelpFile and HelpContextID. These properties perform the same roles as the properties of the same name on the ICommand interface. Respectively, they specify the name of the help file and the numeric value of the topic ID for each control.

When providing context-sensitive help for controls, ESRI's practice again is to use a WinHelp file.

Context-sensitive help for custom property pages is implemented via the standard property page interfaces. It is ESRI's practice to provide What's This help windows as WinHelp topics.

Context-sensitive help for controls on a property page in VB

To add What's This help to a property page implemented in VB, select each control on the Form in turn, press F4 to display the Properties Window, then enter the numeric Help Context ID for the WhatsThisHelp property.

In VB, the property page What's This help can be linked to specific topics by using the WhatsThisHelpID control property in conjunction with the IComPropertyPage members HelpFile and HelpContextID.

Once all values are assigned, add the following code to the implementation of the IComPropertyPage interface.

Private Property Get IComPropertyPage_HelpFile() As String
  IComPropertyPage_HelpFile = "MyHelpfile.hlp"
End Property
Private Property Get IComPropertyPage_HelpContextID(ByVal controlID _
 As Long) As Long
  IComPropertyPage_HelpContextID = m_pFrm.Controls(controlID - 1).WhatsThisHelpID
End Property

When the property page is displayed in a property sheet, the property sheet will forward the call to What's This help to these methods and display the topic specified by the context ID number and the help file.

If you intend to use HtmlHelp to provide popup help, see the previous notes about specifying symbolic ID numbers for HtmlHelp topics. You should also note that HtmlHelp does not support formatted text or diagrams in popup help windows.

Context-sensitive help for controls on a property page in VC++

When you add controls to the dialog box for a property page, ensure the Help ID check box in the control's Properties dialog box is checked. This will ensure resource ID numbers are defined for each control in the resource header file.

What's This help for individual controls on a property page implemented in VC++ can be linked to specific topics by using the Help ID control property in conjunction with the IComPropertyPage members HelpFile and HelpContextID.

Now complete the implementation of IComPropertyPage by returning the appropriate Helpfile string from the implementation of the IComPropertyPage interface. Use the controlIDs for the return value of GetHelpID.

STDMETHODIMP CMyPropPage::GetHelpFile(LONG controlID, BSTR * HelpFile)
{
  if (HelpFile == NULL)
    return E_POINTER;
  
  *HelpFile = ::SysAllocString(OLESTR("MyHelpfile.hlp"));
  
  return S_OK;
}
 
STDMETHODIMP CMyPropPage::GetHelpId(LONG controlID, LONG * helpID)
{
  if (helpID == NULL)
    return E_POINTER;
  
  *helpID = controlID;
  
  return S_OK;
}

Back to top