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