home *** CD-ROM | disk | FTP | other *** search
/ The Best of Select: Games 3 / cd.iso / os2 / pmgnuchs / help.c < prev    next >
Text File  |  1994-04-20  |  12KB  |  412 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. *  Project:    OS/2 PM Port of GNU CHESS 4.0 (PmChess)
  8. *
  9. *  Version:    1994-4-17
  10. *
  11. *   Module:    Help Module 
  12. *
  13. *   System:    OS/2 2.11 using emx0.8h
  14. *
  15. *   Porter:    Revised and ported to OS/2 2.1 by Yibing Fan
  16. *
  17.  *                This source file contains the following functions:
  18.  *
  19.  *                InitHelp()
  20.  *                HelpIndex()
  21.  *                HelpGeneral()
  22.  *                HelpUsingHelp()
  23.  *                HelpKeys()
  24.  *                HelpTutorial()
  25.  *                HelpProductInfo()
  26.  *                DisplayHelpPanel(idPanel)
  27.  *                DestroyHelpInstance()
  28.  *
  29.  *  Concepts   :  help manager
  30.  *
  31.  *  API's      :  WinLoadString
  32.  *                WinCreateHelpInstance
  33.  *                WinAssociateHelpInstance
  34.  *                WinSendMsg
  35.  *                WinDlgBox
  36.  *                WinDestroyHelpInstance
  37.  *                WinMessageBox
  38.  *                WinAlarm
  39.  *
  40.  *    Files    :  OS2.H, STRING.H, MAIN.H, DLG.H, HELP.H, XTRN.H
  41.  *
  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 "pmchess.h"
  53. #include "resource.h"
  54. #include "help.h"
  55.  
  56. #define HELPLIBRARYNAMELEN  20
  57.  
  58. /* If DEBUG is defined, then the help panels will display their
  59.  *  id values on their title bar.  This is useful for determining
  60.  *  which help panels are being shown for each dialog item.  When
  61.  *  the DEBUG directive is not defined, then the panel ids are not
  62.  *  displayed.
  63.  */
  64.  
  65. /* #define  DEBUG */
  66.  
  67. /*
  68.  *  Global variables
  69.  */
  70. extern HAB hab;
  71. BOOL fHelpEnabled;                  /* flag to determine if help is enabled */
  72. static HWND hwndHelpInstance;
  73. static CHAR szLibName[HELPLIBRARYNAMELEN];
  74. static CHAR szWindowTitle[HELPLIBRARYNAMELEN];
  75.  
  76. /**************************************************************************
  77.  *
  78.  *  Name       : InitHelp()
  79.  *
  80.  *  Description:  Initializes the IPF help facility
  81.  *
  82.  *  Concepts:     Called once during initialization of the program
  83.  *
  84.  *                Initializes the HELPINIT structure and creates the
  85.  *                help instance.  If successful, the help instance
  86.  *                is associated with the main window.
  87.  *
  88.  *  API's      :  WinLoadString
  89.  *                WinCreateHelpInstance
  90.  *                WinAssociateHelpInstance
  91.  *
  92.  *  Parameters :  [none]
  93.  *
  94.  *  Return     :  [none]
  95.  *
  96.  *************************************************************************/
  97. VOID InitHelp(VOID)
  98. {
  99.    HELPINIT hini;
  100.  
  101.    /* if we return because of an error, Help will be disabled */
  102.    fHelpEnabled = FALSE;
  103.  
  104.    /* initialize help init structure */
  105.    hini.cb = sizeof(HELPINIT);
  106.    hini.ulReturnCode = 0;
  107.  
  108.    hini.pszTutorialName = (PSZ)NULL;   /* if tutorial added, add name here */
  109.  
  110.    hini.phtHelpTable = (PHELPTABLE)MAKELONG(TEMPLATE_HELP_TABLE, 0xFFFF);
  111.    hini.hmodHelpTableModule = 0;
  112.    hini.hmodAccelActionBarModule = 0;
  113.    hini.idAccelTable = 0;
  114.    hini.idActionBar = 0;
  115.  
  116.    if(!WinLoadString(hab,
  117.                      (HMODULE)0,
  118.                      IDS_HELPWINDOWTITLE,
  119.                      HELPLIBRARYNAMELEN,
  120.                      (PSZ)szWindowTitle))
  121.    {
  122.       SMessageBox(hwndClient, IDMSG_CANNOTLOADSTRING, IDS_CHESS);
  123.       return;
  124.    }
  125.  
  126.    hini.pszHelpWindowTitle = (PSZ)szWindowTitle;
  127.  
  128.    /* if debugging, show panel ids, else don't */
  129. #ifdef DEBUG
  130.    hini.fShowPanelId = CMIC_SHOW_PANEL_ID;
  131. #else
  132.    hini.fShowPanelId = CMIC_HIDE_PANEL_ID;
  133. #endif
  134.  
  135.    if(!WinLoadString(hab,
  136.                      (HMODULE)0,
  137.                      IDS_HELPLIBRARYNAME,
  138.                      HELPLIBRARYNAMELEN,
  139.                      (PSZ)szLibName))
  140.    {
  141.       SMessageBox(hwndClient, IDMSG_CANNOTLOADSTRING, IDS_CHESS);
  142.       return;
  143.    }
  144.  
  145.    hini.pszHelpLibraryName = (PSZ)szLibName;
  146.  
  147.    /* creating help instance */
  148.    hwndHelpInstance = WinCreateHelpInstance(hab, &hini);
  149.  
  150.    if(hwndHelpInstance == NULLHANDLE || hini.ulReturnCode)
  151.    {
  152.       SMessageBox(hwndFrame, IDMSG_HELPLOADERROR, IDS_CHESS);
  153.       return;
  154.    }
  155.  
  156.    /* associate help instance with main frame */
  157.    if(!WinAssociateHelpInstance(hwndHelpInstance, hwndFrame))
  158.    {
  159.          MessageBox(hwndFrame,
  160.                     IDMSG_HELPLOADERROR,
  161.                     MB_OK | MB_ERROR,
  162.                     FALSE);
  163.       return;
  164.    }
  165.  
  166.    /* help manager is successfully initialized so set flag to TRUE */
  167.    fHelpEnabled = TRUE;
  168. }   /* End of InitHelp   */
  169.  
  170.  
  171. /**************************************************************************
  172.  *
  173.  *  Name       : HelpGeneral()
  174.  *
  175.  *  Description: Processes the WM_COMMAND message posted by the
  176.  *               General Help item of the Help menu.
  177.  *
  178.  *  Concepts:    Called from MainCommand when the General Help
  179.  *               menu item is selected.
  180.  *
  181.  *               Sends an HM_EXT_HELP message to the help
  182.  *               instance so that the default Extended Help is
  183.  *               displayed.
  184.  *
  185.  *  API's      : WinSendMsg
  186.  *
  187.  *  Parameters :  [none]
  188.  *
  189.  *  Return     :  [none]
  190.  *
  191.  *************************************************************************/
  192. VOID  HelpGeneral(VOID)
  193. {
  194.     /* this just displays the system extended help panel */
  195.    if(fHelpEnabled)
  196.       if(NULL != WinSendMsg(hwndHelpInstance, HM_EXT_HELP,
  197.                             (MPARAM)NULL, (MPARAM)NULL))
  198.          MessageBox(hwndClient,
  199.                     IDMSG_HELPDISPLAYERROR,
  200.                     MB_OK | MB_ERROR,
  201.                     FALSE);
  202. }   /* End of HelpGeneral  */
  203.  
  204. /**************************************************************************
  205.  *
  206.  *  Name       : HelpUsingHelp()
  207.  *
  208.  *  Description: Processes the WM_COMMAND message posted by the
  209.  *               Using Help item of the Help menu.
  210.  *
  211.  *  Concepts:    Called from MainCommand when the Using Help
  212.  *               menu item is selected.
  213.  *
  214.  *               Sends an HM_DISPLAY_HELP message to the help
  215.  *               instance so that the default Using Help is
  216.  *               displayed.
  217.  *
  218.  *  API's      : WinSendMsg
  219.  *
  220.  *  Parameters :  [none]
  221.  *
  222.  *  Return     :  [none]
  223.  *
  224.  *************************************************************************/
  225. VOID  HelpUsingHelp(VOID)
  226. {
  227.    /* this just displays the system help for help panel */
  228.    if(fHelpEnabled)
  229.       if(NULL != WinSendMsg(hwndHelpInstance, HM_DISPLAY_HELP,
  230.                             (MPARAM)NULL, (MPARAM)NULL))
  231.          MessageBox(hwndClient,
  232.                     IDMSG_HELPDISPLAYERROR,
  233.                     MB_OK | MB_ERROR,
  234.                     FALSE);
  235. }   /* End of HelpUsingHelp   */
  236.  
  237.  
  238. /**************************************************************************
  239.  *
  240.  *  Name       : HelpKeys()
  241.  *
  242.  *  Description: Processes the WM_COMMAND message posted by the
  243.  *               Keys Help item of the Help menu.
  244.  *
  245.  *  Concepts:    Called from MainCommand when the Keys Help
  246.  *               menu item is selected.
  247.  *
  248.  *               Sends an HM_KEYS_HELP message to the help
  249.  *               instance so that the default Keys Help is
  250.  *               displayed.
  251.  *
  252.  *  API's      : WinSendMsg
  253.  *
  254.  *  Parameters :  [none]
  255.  *
  256.  *  Return     :  [none]
  257.  *
  258.  *************************************************************************/
  259. VOID  HelpKeys(VOID)
  260. {
  261.    /* this just displays the system keys help panel */
  262.    if(fHelpEnabled)
  263.       if(NULL != WinSendMsg(hwndHelpInstance, HM_KEYS_HELP,
  264.                             (MPARAM)NULL, (MPARAM)NULL))
  265.          MessageBox(hwndClient,
  266.                     IDMSG_HELPDISPLAYERROR,
  267.                     MB_OK | MB_ERROR,
  268.                     FALSE);
  269. }   /* End of HelpKeys   */
  270.  
  271.  
  272. /**************************************************************************
  273.  *
  274.  *  Name       : HelpIndex()
  275.  *
  276.  *  Description: Processes the WM_COMMAND message posted by the
  277.  *               Help Index item of the Help menu.
  278.  *
  279.  *  Concepts:    Called from MainCommand when the Help Index
  280.  *               menu item is selected.
  281.  *
  282.  *               Sends an HM_INDEX_HELP message to the help
  283.  *               instance so that the default Help Index is
  284.  *               displayed.
  285.  *
  286.  *  API's      : WinSendMsg
  287.  *
  288.  *  Parameters :  [none]
  289.  *
  290.  *  Return     :  [none]
  291.  *
  292.  *************************************************************************/
  293. VOID  HelpIndex(VOID)
  294. {
  295.    /* this just displays the system help index panel */
  296.    if(fHelpEnabled)
  297.       if(NULL != WinSendMsg(hwndHelpInstance, HM_HELP_INDEX,
  298.                              (MPARAM)NULL, (MPARAM)NULL))
  299.          MessageBox(hwndClient,
  300.                     IDMSG_HELPDISPLAYERROR,
  301.                     MB_OK | MB_ERROR,
  302.                     FALSE);
  303. }   /* End of HelpIndex() */
  304.  
  305.  
  306. /**************************************************************************
  307.  *
  308.  *  Name       : HelpTutorial()
  309.  *
  310.  *  Description: Processes the WM_COMMAND message posted by the
  311.  *                Tutorial Help item of the Help menu.  While the
  312.  *                standard template application does not include a
  313.  *                Tutorial menu item, you can add one if your
  314.  *                application has a tutorial.
  315.  *
  316.  *  Concepts:    Called from MainCommand when the Tutorial Help
  317.  *               menu item is selected.
  318.  *
  319.  *  API's      :  WinLoadMessage
  320.  *                WinMessageBox
  321.  *                WinAlarm
  322.  *
  323.  *  Parameters :  [none]
  324.  *
  325.  *  Return     :  [none]
  326.  *
  327.  *************************************************************************/
  328. VOID  HelpTutorial(VOID)
  329. {
  330.    CHAR szText[MESSAGELEN];
  331.  
  332.    /*
  333.     *  Insert code for any tutorial below in place of the message box.
  334.     */
  335.    if(!WinLoadMessage(hab,
  336.                      (HMODULE)NULLHANDLE,
  337.                      IDMSG_YOURTUTORIAL,
  338.                      MESSAGELEN,
  339.                      (PSZ)szText))
  340.    {
  341.       WinAlarm(HWND_DESKTOP, WA_ERROR);
  342.       return;
  343.    }
  344.    WinMessageBox(HWND_DESKTOP,
  345.                  hwndClient,
  346.                  szText,
  347.                  "Tutorial",
  348.                  MB_OK | MB_INFORMATION,
  349.                  FALSE);
  350.  
  351. }   /* End of HelpTutorial   */
  352.  
  353.  
  354.  
  355. /**************************************************************************
  356.  *
  357.  *  Name       : DisplayHelpPanel(idPanel)
  358.  *
  359.  *  Description: Displays the help panel whose id is given
  360.  *
  361.  *  Concepts:    Called whenever a help panel is desired to be
  362.  *               displayed, usually from the WM_HELP processing
  363.  *               of the dialog boxes.
  364.  *
  365.  *               Sends HM_DISPLAY_HELP message to the help instance.
  366.  *
  367.  *  API's      : WinSendMsg
  368.  *
  369.  *  Parameters :  idPanel = panel i.d.
  370.  *
  371.  *  Return     :  [none]
  372.  *
  373.  *************************************************************************/
  374. VOID DisplayHelpPanel(ULONG idPanel)
  375. {
  376.    if(fHelpEnabled)
  377.       if(NULL != WinSendMsg(hwndHelpInstance,
  378.                             HM_DISPLAY_HELP,
  379.                             MPFROMLONG(idPanel),
  380.                             MPFROMSHORT(HM_RESOURCEID)))
  381.          MessageBox(hwndFrame,
  382.                     IDMSG_HELPDISPLAYERROR,
  383.                     MB_OK | MB_ERROR,
  384.                     TRUE);
  385. }   /* End of DisplayHelpPanel   */
  386.  
  387.  
  388. /**************************************************************************
  389.  *
  390.  *  Name       : DestroyHelpInstance()
  391.  *
  392.  *  Description: Destroys the help instance for the application
  393.  *
  394.  *  Concepts:    Called after exit from message loop.
  395.  *
  396.  *               Calls WinDestroyHelpInstance() to destroy the
  397.  *               help instance.
  398.  *
  399.  *  API's      : WinDestroyHelpInstance
  400.  *
  401.  *  Parameters :  [none]
  402.  *
  403.  *  Return     :  [none]
  404.  *
  405.  *************************************************************************/
  406. VOID DestroyHelpInstance(VOID)
  407. {
  408.    if(hwndHelpInstance != NULLHANDLE)
  409.       WinDestroyHelpInstance(hwndHelpInstance);
  410. }   /* End of DestroyHelpInstance   */
  411. /***************************  End of help.c  ****************************/
  412.