Before you call WinCreateHelpInstance, you must allocate memory for and initialize the HELPINIT structure. This structure defines values that IPF needs to create the help instance. Some of the values can be changed by your application after initialization.

The HELPINIT structure and the help table structures referred to by IPF during help processing are contained in the PMHELP.H file. The PMHELP.H file also contains the error codes returned in the event of an unsuccessful call. You include this file in your source code by using the INCL_WINHELP define statement. The following shows the HELPINIT structure.

typedef struct _HELPINIT /* hinit */
{

ULONG          cb;
ULONG          ulReturnCode;
PSZ            pszTutorialName;
PHELPTABLE     phtHelpTable;
HMODULE        hmodHelpTableModule;
HMODULE        hmodAccelActionBarModule;
ULONG          idAccelTable;
ULONG          idActionBar;
PSZ            pszHelpWindowTitle;
ULONG          fShowPanelId;
PSZ            pszHelpLibraryName;
} HELPINIT;

Following are descriptions of the HELPINIT structure fields.

Field Name

Description
cb
The length of the initialization structure. This value can be use to identify the version of IPF being used.
ulReturnCode
The IPF return code
pszTutorialName
A pointer to a tutorial name, if one exists. If this value is NULL, either the application help interface does not include a tutorial, or the tutorial is referenced from a help window. If this value is not NULL, IPF provides a Tutorial choice in the help pull-down and adds a push button to the control area.

If the user selects the Tutorial choice in the pull-down, IPF sends the HM_TUTORIAL message to the application so that it can start the tutorial.

phtHelpTable
If the help table is in memory this ia a pointer to the help table. If the help table is a resource, this is the resource ID ORed with 0xFFFF0000.
hmodHelpTableModule
The name of the resource file that indexes the dynamic link library that contains the help table and its corresponding subtables. If the help table is not being accessed through a dynamic link library, this value is 0.
hmodAccelActionBarModule
The name of the dynamic link library that contains the modified menu bar. If you do not have a modified menu bar, this value is 0.
idAccelTable
The name of the accelerator table if you are using a modified menu bar; otherwise, this value is 0.
idActionBar
The identity of the menu bar (action bar) template. If you are not modifying the menu bar, this value is 0.
pszHelpWindowTitle
A pointer to the name of the title for the main help window. This name can be changed after initialization by sending the message HM_SET_HELP_WINDOW_TITLE.
fShowPanelId
A flag used to append the window ID to the beginning of the help window title in the title bar of the help window. If this flag is set to CMIC_SHOW_PANEL_ID, the window IDs are displayed. If this flag is set to CMIC_HIDE_PANEL_ID or to 0, the window IDs are not displayed.

This flag is useful during the development stages of the help interface.

After initialization, this flag can be toggled with the HM_SET_SHOW_PANEL_ID message.

pszHelpLibraryName
The help library names of the .HLP files containing the help windows. These .HLP files are created by the IPF compiler. When IPF needs to search for a help window, it looks for these library names in the path set by the HELP environment variable. If IPF cannot find a library name in this path, it then searches the current directory.

After initialization, help library names can be specified with the HM_SET_HELP_LIBRARY_NAME message. If multiple libraries are specified, library names must be separated by a blank space.

The following example shows a help facility being initialized. Notice that hmodAccelActionBarModule, idAccelTabl e, and idActionBar have values set to 0; this is because this example uses a standard menu bar.

VOID HelpInit (VOID){
   HELPINIT hini;

   /* if we return because of an error, Help will be disabled */
   fHelpEnabled = FALSE;

   /* initialize help init structure */
   hini.cb = sizeof (HELPINIT)
   hini.ulReturnCode = 0L;

   hini.pszTutorialName = (PSZ)NULL /*if tutorial added, add name here*/

   hini.phtHelpTable = (PHELPTABLE)MAKELONG(JIGSAW_HELP_TABLE, 0xFFFF);
   hini.hmodHelpTableModule = (HMODULE)0;
   hini.hmodAccelActionBarModule = (HMODULE)0;
   hini.idAccelTable = 0;
   hini.idActionBar = 0;

   if (!WinLoadString (habMain,
            (HMODULE)0,
            IDS_HELPWINDOWTITLE,
            HELPLIBRARYNAMELEN,
            (PSZ)szWindowTitle))

   {
     MessageBox (habMain, IDS_CANNOTLOADSTRING, MB_OK | MB_ERROR, FALSE);
     return;
   }

   hini.pszHelpWindowTitle = (PSZ)szWindowTitle;

   /*  if debugging, show panel ids; else, don't   */
#ifdef DEBUG
   hini.fShowPanelId = CMIC_SHOW_PANEL_ID;
#else
   hini.fShowPanelId = CMIC_HIDE_PANEL_ID;
#endif

   if (!WinLoadString (habMain,
            (HMODULE)0,
            IDS_HELPLIBRARYNAME,
            HELPLIBRARYNAMELEN,
            (PSZ)szLibName))
   {
   MessageBox (habMain, IDS_CANNOTLOADSTRING, MB_OK | MB_ERROR, FALSE);
   return;
   }

   hini.pszHelpLibraryName = (PSZ)szLibName;

---

[Back] [Next]