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