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