Path: utzoo!utgpu!news-server.csri.toronto.edu!cs.utexas.edu!sdd.hp.com!spool.mu.edu!uunet!bywater!arnor!ibmman!larrys
From: larrys@watson.ibm.com (Larry Salomon, Jr.)
Newsgroups: comp.os.os2.programmer
Subject: Using the Help Manager
Message-ID: <1991May7.152921.8586@watson.ibm.com>
Date: 7 May 91 15:02:18 GMT
Sender: larrys@ibmman.watson.ibm.com
Reply-To: larrys@yktvmv
Organization: IBM Research
Lines: 185
News-Software: NewsKit 1.2 - LaMail
Nntp-Posting-Host: ibmman

Okay, here's my "seminar" for the month.  ;)  If you have any questions,
feel free to send me mail.

Cheers,
Larry Salomon, Jr. (aka 'Q')            LARRYS@YKTVMV.BITNET
OS/2 Applications and Tools             larrys@ibmman.watson.ibm.com
IBM T.J. Watson Research Center         larrys@eng.clemson.edu
Yorktown Heights, NY

Disclaimer:  The statements and/or opinions stated above are strictly my
own and do not reflect the views of my employer.  Additionally, I have a
reputation for being obnoxious, so don't take any personal attacks too
seriously.

--------- Cut here ---------
                  Enabling your PM Programs to use the
                 OS/2 Information Presentation Facility

Code structure:

In main()...

HELPINIT hiHelpMgr;

// Initialize hiHelpMgr
hiHelpMgr.cb=sizeof(HELPINIT);
hiHelpMgr.ulReturnCode=0L;
hiHelpMgr.pszTutorialName=NULL;
// WND_FRAME is the id of my frame window, and is also
// specified in the WinCreateStdWindow call
hiHelpMgr.phtHelpTable=(PVOID)(0xFFFF0000|WND_FRAME);
hiHelpMgr.hmodHelpTableModule=NULL;
hiHelpMgr.hmodAccelActionBarModule=NULL;
hiHelpMgr.idAccelTable=NULL;
hiHelpMgr.idActionBar=NULL;
hiHelpMgr.pszHelpWindowTitle="MyApp Help";
hiHelpMgr.usShowPanelId=FALSE;
hiHelpMgr.pszHelpLibraryName="MYAPP.HLP";

hwndHelpMgr=WinCreateHelpInstance(hab,&hiHelpMgr);
if ((hwndHelpMgr!=NULL) && (hiHelpMgr.ulReturnCode!=0)) {
   WinDestroyHelpInstance(hwndHelpMgr);
   hwndHelpMgr=NULL;
} /* endif */

if (hwndHelpMgr!=NULL) {
   WinAssociateHelpInstance(hwndHelpMgr,hwndFrame);
} /* endif */

// Create your main window and do the message loop stuff
    :
    :

// After the WinDestroyWindow(hwndFrame)...
if (hwndHelpMgr!=NULL) {
   WinDestroyHelpInstance(hwndHelpMgr);
} /* endif */

= = = = = = = =

In the client window procedure...

Note that you could make your menu items MIS_HELP (in .RC), but I have
experienced problems doing this that I could not trace.  If you treat the
help menu items just like "regular" menu items, you won't have any
worries.

MI_* are the menu item ids

switch (usMsg) {
    :
    :
case MI_HELPFORHELP:
   WinSendMsg(hwndHelpMgr,HM_DISPLAY_HELP,0L,0L);
   break;
case MI_EXTHELP:
   WinSendMsg(hwndHelpMgr,HM_EXT_HELP,0L,0L);
   break;
case MI_KEYSHELP:
   WinSendMsg(hwndHelpMgr,HM_KEYS_HELP,0L,0L);
   break;
case MI_HELPINDEX:
   WinSendMsg(hwndHelpMgr,HM_HELP_INDEX,0L,0L);
   break;
    :
    :
} /* endswitch */

= = = = = = = =

For each dialog box that has a help pushbutton (which should be every
dialog box)...

Although I experience problems sometimes with MIS_HELP menu items, I have
never had trouble with BS_HELP pushbuttons, so make sure your help
pushbutton has this style.

switch (usMsg) {
    :
    :
case WM_INITDLG:
   if (hwndHelpMgr!=NULL) {
      WinAssociateHelpInstance(hwndHelpMgr,hwnd);
   } else {
      WinEnableWindow(WinWindowFromID(hwnd,PB_HELP),FALSE);
   } /* endif */
   break;
case WM_HELP:
   if (hwndHelpMgr!=NULL) {
      switch (SHORT1FROMMP(mp1)) {
      case PB_HELP:
         WinSendMsg(hwndHelpMgr,HM_EXT_HELP,0L,0L);
         break;
      default:
         return WinDefDlgProc(hwnd,usMsg,mp1,mp2);
      } /* endswitch */
   } /* endif */
   break;
    :
    :
} /* endswitch */

= = = = = = = =

In your .RC file

// Note that WND_FRAME is the same id specified in the phtHelpTable field
// of the HELPINIT structure.  This is no coincidence... ;)

HELPTABLE WND_FRAME
{
   // The first id is the frame or dialog id
   // The second id is the subtable id
   // The third id is the panel resource id in the .HLP
   // file of the extended help panel
   HELPITEM WND_FRAME, SUBHLP_FRAME, EXTHLP_FRAME

   // Likewise for every dialog box
      :
}

For every HELPITEM...

HELPSUBTABLE SUBHLP_FRAME
{
   // The first id is the id of the window with the focus
   // when F1 was pressed
   // The second id is the panel resource id in the .HLP
   // file of the panel to be displayed
   //
   // I usually equate the two
   HELPSUBITEM MI_EXIT, MI_EXIT

   // Likewise for every child window and menu item
   // Note that if a child window is not listed here and
   // F1 is pressed, extended help gets displayed
      :
}

= = = = = = = =

In the .IPF file (which gets compiled by IPFC to .HLP)...
:userdoc.
.* Note the hardcoded panel resource id.  This is a gross
.* shortcoming of the IPFC compiler.  However, we can use
.* the C preprocessor to substitute the appropriate #define's
.* Something like this:
.*
.* #include <rc.h>
.* rc.h contains only #define's for the resource related stuff
.*
.* The invocation would be (in the makefile)
.*
.* CL -P \MYAPP\HLP\MYAPP.IPP
.* IF EXIST \MYAPP\HLP\MYAPP.IPF DEL \MYAPP\HLP\MYAPP.IPF
.* REN \MYAPP\HLP\MYAPP.I MYAPP.IPF
.* IPFC \MYAPP\HLP\MYAPP.IPF
.*
.* So instead of ":h1 res=256", we could put ":h1 res=EXTHLP_FRAME"

:h1 res=256.Extended help for MyApp
:p.This is the extended help panel for MyApp
:backm.
:index.
:euserdoc.