larrys@watson.ibm.com (Larry Salomon, Jr.) (05/07/91)
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.cmdglv@pmvax.weeg.uiowa.edu (Mark Gleaves) (05/08/91)
In article <1991May7.152921.8586@watson.ibm.com>, larrys@watson.ibm.com (Larry Salomon, Jr.) writes: >Okay, here's my "seminar" for the month. ;) If you have any questions, >feel free to send me mail. . . . > Enabling your PM Programs to use the > OS/2 Information Presentation Facility > [lots of good code deleted] I think Larry's posting may have been prompted by my question on using the Help Manager about a week ago. Thanks in part to Larry's generous assistance I was able to get a nice set of help screens installed in my program and it's running fine now. If anyone would like to see a copy of a complete (but tiny) application with full Help Manager support, drop me a mail message. Mark -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= Mark Gleaves cmdglv@pmvax.weeg.uiowa.edu "News burst on us like meridian splendour on a blind man. We were over- whelmed with it. . . . Nor was it until some days had elapsed, that we were able to methodise it, or reduce it into form." -- Watkin Tench