Return to help.c CVS log

Up to [OS/2 SDKs] / os232sdk / toolkt20 / c / samples / template

Annotation of os232sdk/toolkt20/c/samples/template/help.c, revision 1.1

1.1     ! root        1: /*==============================================================*\
        !             2:  *  Help.c - routines for the help manager interface
        !             3:  *      Created 1989, 1990 Microsoft Corp.
        !             4:  *--------------------------------------------------------------
        !             5:  *
        !             6:  *  This module contains all the routines for interfacing with
        !             7:  *  the IPF help manager.
        !             8:  *
        !             9:  *--------------------------------------------------------------
        !            10:  *
        !            11:  *  This source file contains the following functions:
        !            12:  *
        !            13:  *          InitHelp()
        !            14:  *          HelpHelpForHelp(mp2)
        !            15:  *          HelpExtended(mp2)
        !            16:  *          HelpKeys(mp2)
        !            17:  *          HelpIndex(mp2)
        !            18:  *          HelpTutorial(mp2)
        !            19:  *          HelpAbout(mp2)
        !            20:  *          DisplayHelpPanel(idPanel)
        !            21:  *          DestroyHelpInstance()
        !            22:  *
        !            23: \*==============================================================*/
        !            24: 
        !            25: /*--------------------------------------------------------------*\
        !            26:  *  Include files, macros, defined constants, and externs
        !            27: \*--------------------------------------------------------------*/
        !            28: 
        !            29: #define  INCL_WINHELP
        !            30: 
        !            31: #include <os2.h>
        !            32: #include <string.h>
        !            33: #include "main.h"
        !            34: #include "dlg.h"
        !            35: #include "help.h"
        !            36: #include "xtrn.h"
        !            37: 
        !            38: #define HELPLIBRARYNAMELEN  20
        !            39: 
        !            40: /* If DEBUG is defined, then the help panels will display their
        !            41:  *  id values on their title bar.  This is useful for determining
        !            42:  *  which help panels are being shown for each dialog item.  When
        !            43:  *  the DEBUG directive is not defined, then the panel ids are not
        !            44:  *  displayed.
        !            45:  */
        !            46: 
        !            47: /* #define  DEBUG */
        !            48: 
        !            49: 
        !            50: /*--------------------------------------------------------------*\
        !            51:  *  Global variables
        !            52: \*--------------------------------------------------------------*/
        !            53: static HWND hwndHelpInstance;
        !            54: static CHAR szLibName[HELPLIBRARYNAMELEN];
        !            55: static CHAR szWindowTitle[HELPLIBRARYNAMELEN];
        !            56: 
        !            57: 
        !            58: /*--------------------------------------------------------------*\
        !            59:  *  Entry point declarations
        !            60: \*--------------------------------------------------------------*/
        !            61: MRESULT EXPENTRY AboutBoxDlgProc(HWND hwnd,
        !            62:                                  USHORT msg,
        !            63:                                  MPARAM mp1,
        !            64:                                  MPARAM mp2);
        !            65: 
        !            66: 
        !            67: 
        !            68: /****************************************************************\
        !            69:  *  Routine for initializing the help manager
        !            70:  *--------------------------------------------------------------
        !            71:  *
        !            72:  *  Name:   InitHelp()
        !            73:  *
        !            74:  *  Purpose: Initializes the IPF help facility
        !            75:  *
        !            76:  *  Usage:  Called once during initialization of the program
        !            77:  *
        !            78:  *  Method: Initializes the HELPINIT structure and creates the
        !            79:  *          help instance.  If successful, the help instance
        !            80:  *          is associated with the main window
        !            81:  *
        !            82:  *  Returns:
        !            83:  *
        !            84: \****************************************************************/
        !            85: VOID InitHelp(VOID)
        !            86: {
        !            87:     HELPINIT hini;
        !            88: 
        !            89:     /* if we return because of an error, Help will be disabled */
        !            90:     fHelpEnabled = FALSE;
        !            91: 
        !            92:     /* initialize help init structure */
        !            93:     hini.cb = sizeof(HELPINIT);
        !            94:     hini.ulReturnCode = NULL;
        !            95: 
        !            96:     hini.pszTutorialName = (PSZ)NULL;   /* if tutorial added, add name here */
        !            97: 
        !            98:     hini.phtHelpTable = (PHELPTABLE)MAKELONG(TEMPLATE_HELP_TABLE, 0xFFFF);
        !            99:     hini.hmodHelpTableModule = NULL;
        !           100:     hini.hmodAccelActionBarModule = NULL;
        !           101:     hini.idAccelTable = NULL;
        !           102:     hini.idActionBar = NULL;
        !           103: 
        !           104:     if(!WinLoadString(hab,
        !           105:                       NULL,
        !           106:                       IDS_HELPWINDOWTITLE,
        !           107:                       HELPLIBRARYNAMELEN,
        !           108:                       (PSZ)szWindowTitle))  {
        !           109: 
        !           110:         MessageBox(hwndMain, IDMSG_CANNOTLOADSTRING, MB_OK | MB_ERROR, FALSE);
        !           111:         return;
        !           112:     }
        !           113: 
        !           114:     hini.pszHelpWindowTitle = (PSZ)szWindowTitle;
        !           115: 
        !           116:     /* if debugging, show panel ids, else don't */
        !           117: #ifdef DEBUG
        !           118:     hini.usShowPanelId = CMIC_SHOW_PANEL_ID;
        !           119: #else
        !           120:     hini.usShowPanelId = CMIC_HIDE_PANEL_ID;
        !           121: #endif
        !           122: 
        !           123:     if(!WinLoadString(hab,
        !           124:                       NULL,
        !           125:                       IDS_HELPLIBRARYNAME,
        !           126:                       HELPLIBRARYNAMELEN,
        !           127:                       (PSZ)szLibName))  {
        !           128: 
        !           129:         MessageBox(hwndMain, IDMSG_CANNOTLOADSTRING, MB_OK | MB_ERROR, FALSE);
        !           130:         return;
        !           131:     }
        !           132: 
        !           133:     hini.pszHelpLibraryName = (PSZ)szLibName;
        !           134: 
        !           135:     /* creating help instance */
        !           136:     hwndHelpInstance = WinCreateHelpInstance(hab, &hini);
        !           137: 
        !           138:     if(hwndHelpInstance == NULL || hini.ulReturnCode)  {
        !           139:         MessageBox(hwndMainFrame, IDMSG_HELPLOADERROR, MB_OK | MB_ERROR, TRUE);
        !           140:         return;
        !           141:     }
        !           142: 
        !           143:     /* associate help instance with main frame */
        !           144:     if(!WinAssociateHelpInstance(hwndHelpInstance, hwndMainFrame))  {
        !           145:         MessageBox(hwndMainFrame, IDMSG_HELPLOADERROR, MB_OK | MB_ERROR, TRUE);
        !           146:         return;
        !           147:     }
        !           148: 
        !           149:     /* help manager is successfully initialized so set flag to TRUE */
        !           150:     fHelpEnabled = TRUE;
        !           151: 
        !           152: }   /* InitHelp() */
        !           153: 
        !           154: 
        !           155: /****************************************************************\
        !           156:  *  Processes the Help for Help command from the menu bar
        !           157:  *--------------------------------------------------------------
        !           158:  *
        !           159:  *  Name:   HelpHelpForHelp(mp2)
        !           160:  *
        !           161:  *  Purpose: Processes the WM_COMMAND message posted by the
        !           162:  *            Help for Help item of the Help menu
        !           163:  *
        !           164:  *  Usage:  Called from MainCommand when the Help for Help
        !           165:  *          menu item is selected
        !           166:  *
        !           167:  *  Method: Sends an HM_DISPLAY_HELP message to the help
        !           168:  *          instance so that the default Help For Help is
        !           169:  *          displayed.
        !           170:  *
        !           171:  *  Returns:
        !           172:  *
        !           173: \****************************************************************/
        !           174: VOID  HelpHelpForHelp(mp2)
        !           175: MPARAM mp2;     /* second parameter of WM_COMMAND message */
        !           176: {
        !           177: 
        !           178:     /* this just displays the system help for help panel */
        !           179:     if(fHelpEnabled)
        !           180:         if(WinSendMsg(hwndHelpInstance, HM_DISPLAY_HELP, NULL, NULL))
        !           181:             MessageBox(hwndMain,
        !           182:                        IDMSG_HELPDISPLAYERROR,
        !           183:                        MB_OK | MB_ERROR,
        !           184:                        FALSE);
        !           185: 
        !           186:     /* This routine currently doesn't use the mp2 parameter but       *\
        !           187:      *  it is referenced here to prevent an 'Unreferenced Parameter'
        !           188:     \*  warning at compile time.                                      */
        !           189:     mp2;
        !           190: 
        !           191: }   /* HelpHelpForHelp() */
        !           192: 
        !           193: 
        !           194: /****************************************************************\
        !           195:  *  Processes the Extended Help command from the menu bar
        !           196:  *--------------------------------------------------------------
        !           197:  *
        !           198:  *  Name:   HelpExtended(mp2)
        !           199:  *
        !           200:  *  Purpose: Processes the WM_COMMAND message posted by the
        !           201:  *            Extended Help item of the Help menu
        !           202:  *
        !           203:  *  Usage:  Called from MainCommand when the Extended Help
        !           204:  *          menu item is selected
        !           205:  *
        !           206:  *  Method: Sends an HM_EXT_HELP message to the help
        !           207:  *          instance so that the default Extended Help is
        !           208:  *          displayed.
        !           209:  *
        !           210:  *  Returns:
        !           211:  *
        !           212: \****************************************************************/
        !           213: VOID  HelpExtended(mp2)
        !           214: MPARAM mp2;     /* second parameter of WM_COMMAND message */
        !           215: {
        !           216: 
        !           217:     /* this just displays the system extended help panel */
        !           218:     if(fHelpEnabled)
        !           219:         if(WinSendMsg(hwndHelpInstance, HM_EXT_HELP, NULL, NULL))
        !           220:             MessageBox(hwndMain,
        !           221:                        IDMSG_HELPDISPLAYERROR,
        !           222:                        MB_OK | MB_ERROR,
        !           223:                        FALSE);
        !           224: 
        !           225:     /* This routine currently doesn't use the mp2 parameter but       *\
        !           226:      *  it is referenced here to prevent an 'Unreferenced Parameter'
        !           227:     \*  warning at compile time.                                      */
        !           228:     mp2;
        !           229: 
        !           230: }   /* HelpExtended() */
        !           231: 
        !           232: 
        !           233: /****************************************************************\
        !           234:  *  Processes the Keys Help command from the menu bar
        !           235:  *--------------------------------------------------------------
        !           236:  *
        !           237:  *  Name:   HelpKeys(mp2)
        !           238:  *
        !           239:  *  Purpose: Processes the WM_COMMAND message posted by the
        !           240:  *            Keys Help item of the Help menu
        !           241:  *
        !           242:  *  Usage:  Called from MainCommand when the Keys Help
        !           243:  *          menu item is selected
        !           244:  *
        !           245:  *  Method: Sends an HM_KEYS_HELP message to the help
        !           246:  *          instance so that the default Keys Help is
        !           247:  *          displayed.
        !           248:  *
        !           249:  *  Returns:
        !           250:  *
        !           251: \****************************************************************/
        !           252: VOID  HelpKeys(mp2)
        !           253: MPARAM mp2;     /* second parameter of WM_COMMAND message */
        !           254: {
        !           255: 
        !           256:     /* this just displays the system keys help panel */
        !           257:     if(fHelpEnabled)
        !           258:         if(WinSendMsg(hwndHelpInstance, HM_KEYS_HELP, NULL, NULL))
        !           259:             MessageBox(hwndMain,
        !           260:                        IDMSG_HELPDISPLAYERROR,
        !           261:                        MB_OK | MB_ERROR,
        !           262:                        FALSE);
        !           263: 
        !           264: 
        !           265:     /* This routine currently doesn't use the mp2 parameter but       *\
        !           266:      *  it is referenced here to prevent an 'Unreferenced Parameter'
        !           267:     \*  warning at compile time.                                      */
        !           268:     mp2;
        !           269: 
        !           270: }   /* HelpKeys() */
        !           271: 
        !           272: 
        !           273: /****************************************************************\
        !           274:  *  Processes the Index Help command from the menu bar
        !           275:  *--------------------------------------------------------------
        !           276:  *
        !           277:  *  Name:   HelpIndex(mp2)
        !           278:  *
        !           279:  *  Purpose: Processes the WM_COMMAND message posted by the
        !           280:  *            Index Help item of the Help menu
        !           281:  *
        !           282:  *  Usage:  Called from MainCommand when the Index Help
        !           283:  *          menu item is selected
        !           284:  *
        !           285:  *  Method: Sends an HM_INDEX_HELP message to the help
        !           286:  *          instance so that the default Index Help is
        !           287:  *          displayed.
        !           288:  *
        !           289:  *  Returns:
        !           290:  *
        !           291: \****************************************************************/
        !           292: VOID  HelpIndex(mp2)
        !           293: MPARAM mp2;     /* second parameter of WM_COMMAND message */
        !           294: {
        !           295: 
        !           296:     /* this just displays the system help index panel */
        !           297:     if(fHelpEnabled)
        !           298:         if(WinSendMsg(hwndHelpInstance, HM_HELP_INDEX, NULL, NULL))
        !           299:             MessageBox(hwndMain,
        !           300:                        IDMSG_HELPDISPLAYERROR,
        !           301:                        MB_OK | MB_ERROR,
        !           302:                        FALSE);
        !           303: 
        !           304: 
        !           305:     /* This routine currently doesn't use the mp2 parameter but       *\
        !           306:      *  it is referenced here to prevent an 'Unreferenced Parameter'
        !           307:     \*  warning at compile time.                                      */
        !           308:     mp2;
        !           309: 
        !           310: }   /* HelpIndex() */
        !           311: 
        !           312: 
        !           313: /****************************************************************\
        !           314:  *  Processes the Tutorial Help command from the menu bar
        !           315:  *--------------------------------------------------------------
        !           316:  *
        !           317:  *  Name:   HelpTutorial(mp2)
        !           318:  *
        !           319:  *  Purpose: Processes the WM_COMMAND message posted by the
        !           320:  *            Tutorial Help item of the Help menu.  While the
        !           321:  *            standard template application does not include a
        !           322:  *            Tutorial menu item, you can add one if your
        !           323:  *            application has a tutorial.
        !           324:  *
        !           325:  *  Usage:  Called from MainCommand when the Tutorial Help
        !           326:  *          menu item is selected
        !           327:  *
        !           328:  *  Method:
        !           329:  *
        !           330:  *  Returns:
        !           331:  *
        !           332: \****************************************************************/
        !           333: VOID  HelpTutorial(mp2)
        !           334: MPARAM mp2;     /* second parameter of WM_COMMAND message */
        !           335: {
        !           336: 
        !           337:    /*--------------------------------------------------------------*\
        !           338:     *  Insert code for any tutorial here
        !           339:    \*--------------------------------------------------------------*/
        !           340: 
        !           341: 
        !           342:     /* This routine currently doesn't use the mp2 parameter but       *\
        !           343:      *  it is referenced here to prevent an 'Unreferenced Parameter'
        !           344:     \*  warning at compile time.                                      */
        !           345:     mp2;
        !           346: 
        !           347: }   /* HelpTutorial() */
        !           348: 
        !           349: 
        !           350: /****************************************************************\
        !           351:  *  Processes the About command from the Help menu
        !           352:  *--------------------------------------------------------------
        !           353:  *
        !           354:  *  Name:   HelpAbout(mp2)
        !           355:  *
        !           356:  *  Purpose: Processes the WM_COMMAND message posted by the
        !           357:  *            About item of the Help menu
        !           358:  *
        !           359:  *  Usage:  Called from MainCommand when the About
        !           360:  *          menu item is selected
        !           361:  *
        !           362:  *  Method: Calls WinDlgBox to display the about box dialog.
        !           363:  *
        !           364:  *  Returns:
        !           365:  *
        !           366: \****************************************************************/
        !           367: VOID  HelpAbout(mp2)
        !           368: MPARAM mp2;     /* second parameter of WM_COMMAND message */
        !           369: {
        !           370: 
        !           371:     /* display the AboutBox dialog */
        !           372:     WinDlgBox(HWND_DESKTOP,
        !           373:               hwndMain,
        !           374:               (PFNWP)AboutBoxDlgProc,
        !           375:               NULL,
        !           376:               IDD_ABOUTBOX,
        !           377:               (PVOID)NULL);
        !           378: 
        !           379:     /* This routine currently doesn't use the mp2 parameter but       *\
        !           380:      *  it is referenced here to prevent an 'Unreferenced Parameter'
        !           381:     \*  warning at compile time.                                      */
        !           382:     mp2;
        !           383: 
        !           384: }   /* HelpAbout() */
        !           385: 
        !           386: 
        !           387: /****************************************************************\
        !           388:  *  Displays the help panel indicated
        !           389:  *--------------------------------------------------------------
        !           390:  *
        !           391:  *  Name:   DisplayHelpPanel(idPanel)
        !           392:  *
        !           393:  *  Purpose: Displays the help panel whose id is given
        !           394:  *
        !           395:  *  Usage:  Called whenever a help panel is desired to be
        !           396:  *          displayed, usually from the WM_HELP processing
        !           397:  *          of the dialog boxes
        !           398:  *
        !           399:  *  Method: Sends HM_DISPLAY_HELP message to the help instance
        !           400:  *
        !           401:  *  Returns:
        !           402:  *
        !           403: \****************************************************************/
        !           404: VOID DisplayHelpPanel(idPanel)
        !           405: SHORT idPanel;      /* ID of the help panel to be displayed */
        !           406: {
        !           407: 
        !           408:     if(fHelpEnabled)
        !           409:         if(WinSendMsg(hwndHelpInstance,
        !           410:                       HM_DISPLAY_HELP,
        !           411:                       MPFROMLONG(MAKELONG(idPanel, NULL)),
        !           412:                       MPFROMSHORT(HM_RESOURCEID)))  {
        !           413: 
        !           414:             MessageBox(hwndMainFrame,
        !           415:                        IDMSG_HELPDISPLAYERROR,
        !           416:                        MB_OK | MB_ERROR,
        !           417:                        TRUE);
        !           418:         }
        !           419: 
        !           420: 
        !           421: }   /* DisplayHelpPanel() */
        !           422: 
        !           423: 
        !           424: 
        !           425: /****************************************************************\
        !           426:  *  Destroys the help instance
        !           427:  *--------------------------------------------------------------
        !           428:  *
        !           429:  *  Name:   DestroyHelpInstance(VOID)
        !           430:  *
        !           431:  *  Purpose: Destroys the help instance for the application
        !           432:  *
        !           433:  *  Usage:  Called after exit from message loop
        !           434:  *
        !           435:  *  Method: Calls WinDestroyHelpInstance() to destroy the
        !           436:  *          help instance
        !           437:  *
        !           438:  *  Returns:
        !           439:  *
        !           440: \****************************************************************/
        !           441: VOID DestroyHelpInstance(VOID)
        !           442: {
        !           443: 
        !           444:     if(hwndHelpInstance != NULL)  {
        !           445:         WinDestroyHelpInstance(hwndHelpInstance);
        !           446:     }
        !           447: 
        !           448: }   /* DestroyHelpInstance() */

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.