The OpenEdge Hive

WinHelp is history... HTML Help is the future. The API for HTML Help is implemented in hhctrl.ocx (don't let the filename fool you; the ocx contains both an ActiveX control and API functions). First let's take a look at the definition:

&GLOBAL-DEFINE HH_DISPLAY_TOPIC 0
&GLOBAL-DEFINE HH_KEYWORD_LOOKUP 13
&GLOBAL-DEFINE HH_DISPLAY_TEXT_POPUP 14
 
PROCEDURE HtmlHelpA EXTERNAL "hhctrl.ocx" PERSISTENT :
   DEFINE INPUT PARAMETER  hwndCaller AS LONG.
   DEFINE INPUT PARAMETER  pszFile    AS CHARACTER.
   DEFINE INPUT PARAMETER  uCommand   AS LONG.
   DEFINE INPUT PARAMETER  dwData     AS LONG.
   DEFINE RETURN PARAMETER hwndHelp   AS LONG.
END PROCEDURE.

Notice the **PERSISTENT** keyword: it is required for this function!
hwndCaller is the HWND of the calling window. The help-window stays on top of this calling window. You can specify hwndCaller=0 if you don't like that stay-on-top behaviour.
pszFile is (depending on uCommand) the name of the helpfile, combined with the name of the topic file, combined with the name of the window class in which you want to show the topic. For example "apisite.chm::/playsounda.html>mainwin".
pszFile can also be used to specify the text to show in a popup-window (if uCommand is HH_DISPLAY_TEXT_POPUP) as demonstrated on the next page, Popup windows from HTML Help

pszFile can also be NULL for some values of uCommand. That is going to be a problem in the way I defined the function using a CHAR parameter.
uCommand specifies what the function is supposed to do; examples follow.
dwData depends on uCommand, it is most often a pointer to some structure or simply NULL.
hwndHelp (the return parameter) is the HWND of the created help window. It can be used for manipulating the help window from within your application.
The following example opens helpfile apisite.chm and navigates to a specific topic file (playsounda.html).

RUN ShowHelpTopic ( FRAME {&FRAME-NAME}:HANDLE,
                    "PlaySoundA").
 
PROCEDURE ShowHelpTopic :
  DEFINE INPUT PARAMETER hParent  AS HANDLE  NO-UNDO.
  DEFINE INPUT PARAMETER cTopic   AS CHARACTER    NO-UNDO.
 
  DEFINE VARIABLE        hWndHelp AS INTEGER NO-UNDO.
 
  IF NOT VALID-HANDLE(hParent) THEN 
     hParent = CURRENT-WINDOW:HANDLE.
 
  IF cTopic NE '' THEN 
     cTopic = "::/" + cTopic + ".html".
 
  RUN HtmlHelpA( hParent:HWND , 
                 "apisite.chm" + cTopic, 
                 {&HH_DISPLAY_TOPIC},
                 0, 
                 OUTPUT hWndHelp).
END PROCEDURE.

The next example uses keyword lookup. The input parameter is a ";" separated list of keywords. Keyword lookup is case sensitive!! If exactly one matching topic is found it will immediately be shown. If more than one match is found you will get to see a menu.
What happens if no matches are found? Well, that depends on the members in the lpHH_AKLINK structure. This example is set to open the helpfile and show the "Index" tab. It could also have been set to go to a specific topic (using the pszUrl field) or to show a messagebox (using pszMsgText and pszMsgTitle)

 
RUN ShowHelpKeyword ( FRAME {&FRAME-NAME}:HANDLE,
                      "BrowseForFolder;SHBrowseForFolder").
 
PROCEDURE ShowHelpKeyword :
  DEFINE INPUT PARAMETER hParent   AS HANDLE  NO-UNDO.
  DEFINE INPUT PARAMETER cKeywords AS CHARACTER    NO-UNDO.
 
  DEFINE VARIABLE        hWndHelp    AS INTEGER NO-UNDO.
  DEFINE VARIABLE        lpKeywords  AS MEMPTR  NO-UNDO.
  DEFINE VARIABLE        lpHH_AKLINK AS MEMPTR  NO-UNDO.
 
  IF cKeywords="" THEN RETURN.
 
  IF NOT VALID-HANDLE(hParent) THEN 
     hParent = CURRENT-WINDOW:HANDLE.
 
  /* first use HH_DISPLAY_TOPIC to initialize the help window */
  RUN ShowHelpTopic (hParent, "").
  /* should really check if this succeeded.... */
 
  /* if succeeded then use HH_KEYWORD_LOOKUP */
  SET-SIZE (lpKeywords)     = LENGTH(cKeywords) + 2.
  PUT-STRING(lpKeywords, 1) = cKeywords.
 
  SET-SIZE (lpHH_AKLINK)    = 32.
  PUT-LONG (lpHH_AKLINK, 1) = GET-SIZE(lpHH_AKLINK).
  PUT-LONG (lpHH_AKLINK, 5) = INT(FALSE). /* reserved, always FALSE */
  PUT-LONG (lpHH_AKLINK, 9) = GET-POINTER-VALUE(lpKeywords).
  PUT-LONG (lpHH_AKLINK,13) = 0.          /* pszUrl      */
  PUT-LONG (lpHH_AKLINK,17) = 0.          /* pszMsgText  */
  PUT-LONG (lpHH_AKLINK,21) = 0.          /* pszMsgTitle */
  PUT-LONG (lpHH_AKLINK,25) = 0.          /* pszWindow   */
  PUT-LONG (lpHH_AKLINK,29) = INT(TRUE).  /* fIndexOnFail */
 
  RUN HtmlHelpA( hParent:HWND , 
                 "apisite.chm", 
                 {&HH_KEYWORD_LOOKUP},
                 GET-POINTER-VALUE(lpHH_AKLINK), 
                 OUTPUT hWndHelp).
 
  SET-SIZE (lpHH_AKLINK) = 0.
  SET-SIZE (lpKeywords) = 0.
 
END PROCEDURE.