home *** CD-ROM | disk | FTP | other *** search
/ The Developer Connection…ice Driver Kit for OS/2 3 / DEV3-D1.ISO / devtools / os2tk21j / c / samples / jigsaw / jighelp.c__ / jighelp.c
Encoding:
C/C++ Source or Header  |  1993-03-12  |  16.5 KB  |  531 lines
  1. /******************************************************************************
  2. *
  3. *  File Name   : JIGHELP.C
  4. *
  5. *  Description : This module contains all the routines for interfacing with
  6. *                the IPF help manager.
  7. *
  8. *  Concepts    : Using the Information Presentation Facility for help
  9. *
  10. *  Entry Points:
  11. *                AboutBoxDlgProc()
  12. *                DestroyHelpInstance()
  13. *                DisplayHelpPanel()
  14. *                HelpAbout()
  15. *                HelpExtended()
  16. *                HelpHelpForHelp()
  17. *                HelpIndex()
  18. *                HelpInit()
  19. *                HelpTutorial()
  20. *                ShowDlgHelp()
  21. *
  22. *  Copyright (C) 1992 IBM Corporation
  23. *
  24. *      DISCLAIMER OF WARRANTIES.  The following [enclosed] code is
  25. *      sample code created by IBM Corporation. This sample code is not
  26. *      part of any standard or IBM product and is provided to you solely
  27. *      for  the purpose of assisting you in the development of your
  28. *      applications.  The code is provided "AS IS", without
  29. *      warranty of any kind.  IBM shall not be liable for any damages
  30. *      arising out of your use of the sample code, even if they have been
  31. *      advised of the possibility of such damages.                                                    *
  32. *
  33. ******************************************************************************/
  34.  
  35. /*--------------------------------------------------------------
  36.  *  Include files, macros, defined constants, and externs
  37.   --------------------------------------------------------------*/
  38.  
  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. /*
  48.    A better method of defining this directive is in a parameter to the
  49.    compiler (-DDEBUG).
  50.  
  51. #define  DEBUG
  52. */
  53.  
  54. #include "jigsaw.h"
  55. #include "globals.h"
  56. #include "jighelp.h"
  57. #include <string.h>
  58.  
  59. /*--------------------------------------------------------------*\
  60.  *  Local Static Variables
  61. \*--------------------------------------------------------------*/
  62. static HWND hwndHelpInstance;
  63. static CHAR szLibName[HELPLIBRARYNAMELEN];
  64. static CHAR szWindowTitle[HELPLIBRARYNAMELEN];
  65. static BOOL fHelpEnabled = FALSE;
  66.  
  67.  
  68. /*--------------------------------------------------------------*\
  69.  *  Entry point declarations
  70. \*--------------------------------------------------------------*/
  71. MRESULT EXPENTRY AboutBoxDlgProc(HWND hwnd, ULONG msg,
  72.              MPARAM mp1, MPARAM mp2);
  73. VOID ShowDlgHelp(HWND hwnd);
  74.  
  75.  
  76. /****************************************************************\
  77.  *  Routine for initializing the help manager
  78.  *--------------------------------------------------------------
  79.  *
  80.  *  Name:   HelpInit()
  81.  *
  82.  *  Purpose: Initializes the IPF help facility
  83.  *
  84.  *  Usage:  Called once during initialization of the program
  85.  *
  86.  *  Method: Initializes the HELPINIT structure and creates the
  87.  *       help instance.  If successful, the help instance
  88.  *       is associated with the main window
  89.  *
  90.  *  Returns:
  91.  *
  92. \****************************************************************/
  93. VOID HelpInit(VOID)
  94. {
  95.     HELPINIT hini;
  96.  
  97.     /* if we return because of an error, Help will be disabled */
  98.     fHelpEnabled = FALSE;
  99.  
  100.     /* inititalize help init structure */
  101.     hini.cb = sizeof(HELPINIT);
  102.     hini.ulReturnCode = 0L;
  103.  
  104.     hini.pszTutorialName = (PSZ)NULL;   /* if tutorial added, add name here */
  105.  
  106.     hini.phtHelpTable = (PHELPTABLE)MAKELONG(JIGSAW_HELP_TABLE, 0xFFFF);
  107.     hini.hmodHelpTableModule = (HMODULE)0;
  108.     hini.hmodAccelActionBarModule = (HMODULE)0;
  109.     hini.idAccelTable = 0;
  110.     hini.idActionBar = 0;
  111.  
  112.     if(!WinLoadString(habMain,
  113.             (HMODULE)0,
  114.             IDS_HELPWINDOWTITLE,
  115.             HELPLIBRARYNAMELEN,
  116.             (PSZ)szWindowTitle))  {
  117.  
  118.    MessageBox(hwndFrame, IDS_CANNOTLOADSTRING, MB_OK | MB_ERROR, FALSE);
  119.    return;
  120.     }
  121.  
  122.     hini.pszHelpWindowTitle = (PSZ)szWindowTitle;
  123.  
  124.     /* if debugging, show panel ids, else don't */
  125. #ifdef DEBUG
  126.     hini.fShowPanelId = CMIC_SHOW_PANEL_ID;
  127. #else
  128.     hini.fShowPanelId = CMIC_HIDE_PANEL_ID;
  129. #endif
  130.  
  131.     if(!WinLoadString(habMain,
  132.             (HMODULE)0,
  133.             IDS_HELPLIBRARYNAME,
  134.             HELPLIBRARYNAMELEN,
  135.             (PSZ)szLibName))   {
  136.  
  137.    MessageBox(hwndFrame, IDS_CANNOTLOADSTRING, MB_OK | MB_ERROR, FALSE);
  138.    return;
  139.     }
  140.  
  141.     hini.pszHelpLibraryName = (PSZ)szLibName;
  142.  
  143.     /* creating help instance */
  144.     hwndHelpInstance = WinCreateHelpInstance(habMain, &hini);
  145.  
  146.     if(!hwndHelpInstance || hini.ulReturnCode)   {
  147.    MessageBox(hwndFrame,
  148.          IDS_HELPLOADERROR,
  149.          MB_OK | MB_ERROR,
  150.          TRUE);
  151.    return;
  152.     }
  153.  
  154.     /* associate help instance with main frame */
  155.     if(!WinAssociateHelpInstance(hwndHelpInstance, hwndFrame)) {
  156.    MessageBox(hwndFrame,
  157.          IDS_HELPLOADERROR,
  158.          MB_OK | MB_ERROR,
  159.          TRUE);
  160.    return;
  161.     }
  162.  
  163.     /* help manager is successfully initialized so set flag to TRUE */
  164.     fHelpEnabled = TRUE;
  165.  
  166. }   /* HelpInit() */
  167.  
  168.  
  169. /****************************************************************\
  170.  *  Processes the Help for Help command from the menu bar
  171.  *--------------------------------------------------------------
  172.  *
  173.  *  Name:   HelpHelpForHelp(mp2)
  174.  *
  175.  *  Purpose: Processes the WM_COMMAND message posted by the
  176.  *         Help for Help item of the Help menu
  177.  *
  178.  *  Usage:  Called from MainCommand when the Help for Help
  179.  *       menu item is selected
  180.  *
  181.  *  Method: Sends an HM_DISPLAY_HELP message to the help
  182.  *       instance so that the default Help For Help is
  183.  *       displayed.
  184.  *
  185.  *  Returns:
  186.  *
  187. \****************************************************************/
  188. VOID  HelpHelpForHelp(mp2)
  189. MPARAM mp2;   /* second parameter of WM_COMMAND message */
  190. {
  191.  
  192.     /* this just displays the system help for help panel */
  193.     if(fHelpEnabled)
  194.    if(WinSendMsg(hwndHelpInstance, HM_DISPLAY_HELP, NULL, NULL))
  195.        MessageBox(hwndFrame,
  196.              IDS_HELPDISPLAYERROR,
  197.              MB_OK | MB_ERROR,
  198.              FALSE);
  199.  
  200.     /* This routine currently doesn't use the mp2 parameter but       *\
  201.      *  it is referenced here to prevent an 'Unreferenced Parameter'
  202.     \*   warning at compile time.                  */
  203.     mp2;
  204.  
  205. }   /* HelpHelpForHelp() */
  206.  
  207.  
  208. /****************************************************************\
  209.  *  Processes the Extended Help command from the menu bar
  210.  *--------------------------------------------------------------
  211.  *
  212.  *  Name:   HelpExtended( VOID )
  213.  *
  214.  *  Purpose: Processes the WM_COMMAND message posted by the
  215.  *         Extended Help item of the Help menu
  216.  *
  217.  *  Usage:  Called from MainCommand when the Extended Help
  218.  *       menu item is selected
  219.  *
  220.  *  Method: Sends an HM_EXT_HELP message to the help
  221.  *       instance so that the default Extended Help is
  222.  *       displayed.
  223.  *
  224.  *  Returns:
  225.  *
  226. \****************************************************************/
  227. VOID  HelpExtended( VOID )
  228. {
  229.  
  230.     /* this just displays the system extended help panel */
  231.     if(fHelpEnabled)
  232.  
  233. /*
  234.     if (WinSendMsg(hwndHelpInstance,PANEL_EXTENDED_CONTENTS,
  235.                  MPFROMSHORT(PANEL_EXTENDED_CONTENTS), NULL))
  236.        MessageBox(hwndFrame,
  237.              IDS_HELPDISPLAYERROR,
  238.              MB_OK | MB_ERROR,
  239.              FALSE);
  240. */
  241.     if(WinSendMsg(hwndHelpInstance, HM_EXT_HELP, NULL, NULL))
  242.        MessageBox(hwndFrame,
  243.              IDS_HELPDISPLAYERROR,
  244.              MB_OK | MB_ERROR,
  245.              FALSE);
  246. }   /* HelpExtended() */
  247.  
  248.  
  249.  
  250. /****************************************************************\
  251.  *  Processes the Keys Help command from the menu bar
  252.  *--------------------------------------------------------------
  253.  *
  254.  *  Name:   HelpKeys(mp2)
  255.  *
  256.  *  Purpose: Processes the WM_COMMAND message posted by the
  257.  *         Keys Help item of the Help menu
  258.  *
  259.  *  Usage:  Called from MainCommand when the Keys Help
  260.  *       menu item is selected
  261.  *
  262.  *  Method: Sends an HM_KEYS_HELP message to the help
  263.  *       instance so that the default Keys Help is
  264.  *       displayed.
  265.  *
  266.  *  Returns:
  267.  *
  268. \****************************************************************/
  269. /*VOID  HelpKeys(mp2)
  270. MPARAM mp2;    second parameter of WM_COMMAND message
  271. {                                                      */
  272.  
  273.     /* this just displays the system keys help panel
  274.     if(fHelpEnabled)
  275.    if(WinSendMsg(hwndHelpInstance, PANEL_KEYS_CONTENTS, MPFROMSHORT(PANEL_KEYS_CONTENTS), NULL))
  276.        MessageBox(hwndFrame,
  277.              IDS_HELPDISPLAYERROR,
  278.              MB_OK | MB_ERROR,
  279.              FALSE);
  280.                                                       */
  281.  
  282.     /* This routine currently doesn't use the mp2 parameter but       *\
  283.      *  it is referenced here to prevent an 'Unreferenced Parameter'
  284.     \*   warning at compile time.                  */
  285.  /*   mp2;
  286.  
  287. }    HelpKeys() */
  288.  
  289.  
  290. /****************************************************************\
  291.  *  Processes the Index Help command from the menu bar
  292.  *--------------------------------------------------------------
  293.  *
  294.  *  Name:   HelpIndex(mp2)
  295.  *
  296.  *  Purpose: Processes the WM_COMMAND message posted by the
  297.  *         Index Help item of the Help menu
  298.  *
  299.  *  Usage:  Called from MainCommand when the Index Help
  300.  *       menu item is selected
  301.  *
  302.  *  Method: Sends an HM_INDEX_HELP message to the help
  303.  *       instance so that the default Index Help is
  304.  *       displayed.
  305.  *
  306.  *  Returns:
  307.  *
  308. \****************************************************************/
  309. VOID  HelpIndex(mp2)
  310. MPARAM mp2;   /* second parameter of WM_COMMAND message */
  311. {
  312.  
  313.     /* this just displays the system help index panel */
  314.     if(fHelpEnabled)
  315.    if(WinSendMsg(hwndHelpInstance, HM_HELP_INDEX, NULL, NULL))
  316.        MessageBox(hwndFrame,
  317.              IDS_HELPDISPLAYERROR,
  318.              MB_OK | MB_ERROR,
  319.              FALSE);
  320.  
  321.  
  322.     /* This routine currently doesn't use the mp2 parameter but       *\
  323.      *  it is referenced here to prevent an 'Unreferenced Parameter'
  324.     \*   warning at compile time.                  */
  325.     mp2;
  326.  
  327. }   /* HelpIndex() */
  328.  
  329.  
  330. /****************************************************************\
  331.  *  Processes the Tutorial Help command from the menu bar
  332.  *--------------------------------------------------------------
  333.  *
  334.  *  Name:   HelpTutorial(mp2)
  335.  *
  336.  *  Purpose: Processes the WM_COMMAND message posted by the
  337.  *         Tutorial Help item of the Help menu.  While the
  338.  *         standard template application does not include a
  339.  *         Tutorial menu item, you can add one if your
  340.  *         application has a tutorial.
  341.  *
  342.  *  Usage:  Called from MainCommand when the Tutorial Help
  343.  *       menu item is selected
  344.  *
  345.  *  Method:
  346.  *
  347.  *  Returns:
  348.  *
  349. \****************************************************************/
  350. VOID  HelpTutorial(mp2)
  351. MPARAM mp2;   /* second parameter of WM_COMMAND message */
  352. {
  353.  
  354.    /*--------------------------------------------------------------*\
  355.     *  Insert code for any tutorial here
  356.    \*--------------------------------------------------------------*/
  357.  
  358.  
  359.     /* This routine currently doesn't use the mp2 parameter but       *\
  360.      *  it is referenced here to prevent an 'Unreferenced Parameter'
  361.     \*   warning at compile time.                  */
  362.     mp2;
  363.  
  364. }   /* HelpTutorial() */
  365.  
  366. /****************************************************************\
  367.  *  Processes the About command from the Help menu
  368.  *--------------------------------------------------------------
  369.  *
  370.  *  Name:   HelpAbout(mp2)
  371.  *
  372.  *  Purpose: Processes the WM_COMMAND message posted by the
  373.  *         About item of the Help menu
  374.  *
  375.  *  Usage:  Called from MainCommand when the About
  376.  *       menu item is selected
  377.  *
  378.  *  Method: Calls WinDlgBox to display the about box dialog.
  379.  *
  380.  *  Returns:
  381.  *
  382. \****************************************************************/
  383. VOID  HelpAbout(mp2)
  384. MPARAM mp2;   /* second parameter of WM_COMMAND message */
  385. {
  386.     /* display the AboutBox dialog */
  387.     WinDlgBox(HWND_DESKTOP,
  388.          hwndFrame,
  389.          (PFNWP)AboutBoxDlgProc,
  390.          (HMODULE)0,
  391.          IDD_ABOUTBOX,
  392.          (PVOID)NULL);
  393.  
  394.     /* This routine currently doesn't use the mp2 parameter but       *\
  395.      *  it is referenced here to prevent an 'Unreferenced Parameter'
  396.     \*   warning at compile time.                  */
  397.     mp2;
  398.  
  399. }   /* HelpAbout() */
  400.  
  401.  
  402. /****************************************************************\
  403.  *  Displays the help panel indicated
  404.  *--------------------------------------------------------------
  405.  *
  406.  *  Name:   DisplayHelpPanel(idPanel)
  407.  *
  408.  *  Purpose: Displays the help panel whose id is given
  409.  *
  410.  *  Usage:  Called whenever a help panel is desired to be
  411.  *       displayed, usually from the WM_HELP processing
  412.  *       of the dialog boxes
  413.  *
  414.  *  Method: Sends HM_DISPLAY_HELP message to the help instance
  415.  *
  416.  *  Returns:
  417.  *
  418. \****************************************************************/
  419. VOID DisplayHelpPanel(SHORT idPanel) /* ID of help panel to display */
  420. {
  421.     if (fHelpEnabled)
  422.       if (WinSendMsg(hwndHelpInstance, HM_DISPLAY_HELP,
  423.                      MPFROM2SHORT(idPanel, NULL), MPFROMSHORT(HM_RESOURCEID)))
  424.  
  425.          MessageBox(hwndFrame, IDS_HELPDISPLAYERROR, MB_OK | MB_ERROR, TRUE);
  426.  
  427. }   /* DisplayHelpPanel() */
  428.  
  429.  
  430.  
  431. /****************************************************************\
  432.  *  Destroys the help instance
  433.  *--------------------------------------------------------------
  434.  *
  435.  *  Name:   DestroyHelpInstance(VOID)
  436.  *
  437.  *  Purpose: Destroys the help instance for the application
  438.  *
  439.  *  Usage:  Called after exit from message loop
  440.  *
  441.  *  Method: Calls WinDestroyHelpInstance() to destroy the
  442.  *       help instance
  443.  *
  444.  *  Returns:
  445.  *
  446. \****************************************************************/
  447. VOID DestroyHelpInstance(VOID)
  448. {
  449.     if(hwndHelpInstance)  {
  450.    WinDestroyHelpInstance(hwndHelpInstance);
  451.     }
  452.  
  453. }   /* DestroyHelpInstance() */
  454. /****************************************************************\
  455.  *  Dialog procedure for the About dialog box
  456.  *--------------------------------------------------------------
  457.  *
  458.  *  Name:   AboutBoxDlgProc(hwnd, msg, mp1, mp2)
  459.  *
  460.  *  Purpose: Processes all messages sent to the About Box
  461.  *
  462.  *  Usage:  Called for each message sent to the About Box
  463.  *       dialog box.
  464.  *
  465.  *  Method: the about box only has a button control so this
  466.  *       routine only processes WM_COMMAND messages.  Any
  467.  *       WM_COMMAND posted must have come from the Ok
  468.  *       button so we dismiss the dialog upon receiving it.
  469.  *
  470.  *  Returns: Dependent upon message sent
  471.  *
  472. \****************************************************************/
  473. MRESULT EXPENTRY AboutBoxDlgProc(HWND hwnd, ULONG msg,MPARAM mp1,MPARAM mp2)
  474. {
  475.     switch(msg)  {
  476.    case WM_COMMAND:
  477.        /* no matter what the command, close the dialog */
  478.        WinDismissDlg(hwnd, TRUE);
  479.        break;
  480. /**********  Remove this code for now
  481.    case WM_HELP:
  482.        ShowDlgHelp(hwnd);
  483.        break;             ************/
  484.  
  485.    default:
  486.        return(WinDefDlgProc(hwnd, msg, mp1, mp2));
  487.        break;
  488.     }
  489.  
  490.     return 0L;
  491.  
  492. }   /* AboutBoxDlgProc() */
  493. /****************************************************************\
  494.  *  Shows the help panel for the given dialog window
  495.  *--------------------------------------------------------------
  496.  *
  497.  *  Name:   ShowDlgHelp(hwnd)
  498.  *
  499.  *  Purpose: Displays the help panel for the current selected
  500.  *        item in the dialog window
  501.  *
  502.  *  Usage:  Called each time a WM_HELP message is posted to
  503.  *       a dialog
  504.  *
  505.  *  Method: gets the id value of the window and determine which
  506.  *       help panel to display.  Then sends a message to
  507.  *       the help instance to display the panel.  If the dialog
  508.  *       or item is not included here, then the unknown dialog
  509.  *       or unknown item panel is displayed.
  510.  *
  511.  *  Returns:
  512.  *
  513. \****************************************************************/
  514. VOID ShowDlgHelp(hwnd)
  515. HWND hwnd;   /* handle of list box window */
  516. {
  517.     SHORT idDlg, idItem;
  518.     HWND  hwndFocus;
  519.  
  520.     /* get the id of the dialog box */
  521.     idDlg = WinQueryWindowUShort(hwnd, QWS_ID);
  522.  
  523.     /* finds which window has the focus and gets its id */
  524.     hwndFocus = WinQueryFocus(HWND_DESKTOP);
  525.     idItem = WinQueryWindowUShort(hwndFocus, QWS_ID);
  526.  
  527.  
  528. }   /* ShowDlgHelp() */
  529.  
  530. /******************************  END JIGHELP.C  ******************************/
  531.