home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / tolkit45.zip / os2tk45 / samples / os2 / npipe / svrphelp.c < prev    next >
C/C++ Source or Header  |  1999-05-11  |  15KB  |  477 lines
  1. /*==============================================================*\
  2.  *  Svrphelp.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 "svrpmain.h"
  47. #include "svrphelp.h"
  48. #include "svrpxtrn.h"
  49. #include "svrpglbl.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(SVRP_HELP_TABLE, 0xFFFF);
  112.    hini.hmodHelpTableModule = (HMODULE)0;
  113.    hini.hmodAccelActionBarModule = (HMODULE)0;
  114.    hini.idAccelTable = 0;
  115.    hini.idActionBar = 0;
  116.  
  117.    if(!WinLoadString(hab,
  118.                      (HMODULE)0,
  119.                      IDS_HELPWINDOWTITLE,
  120.                      HELPLIBRARYNAMELEN,
  121.                      (PSZ)szWindowTitle))
  122.    {
  123.       MessageBox(hwndMain, IDMSG_CANNOTLOADSTRING, MB_OK | MB_ERROR, 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.                      (HMODULE)0,
  138.                      IDS_HELPLIBRARYNAME,
  139.                      HELPLIBRARYNAMELEN,
  140.                      (PSZ)szLibName))
  141.    {
  142.       MessageBox(hwndMain, IDMSG_CANNOTLOADSTRING, MB_OK | MB_ERROR, 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, MB_OK | MB_ERROR, TRUE);
  154.       return;
  155.    }
  156.  
  157.    /* associate help instance with main frame */
  158.    if(!WinAssociateHelpInstance(hwndHelpInstance, hwndMainFrame))
  159.    {
  160.       MessageBox(hwndMainFrame, IDMSG_HELPLOADERROR, MB_OK | MB_ERROR, 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)  /* second parameter of WM_COMMAND message */
  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.                     MB_OK | MB_ERROR,
  200.                     FALSE);
  201.       }
  202.    }
  203. }   /* HelpHelpForHelp() */
  204.  
  205.  
  206. /****************************************************************\
  207.  *  Processes the Extended Help command from the menu bar
  208.  *--------------------------------------------------------------
  209.  *
  210.  *  Name:   HelpExtended(mp2)
  211.  *
  212.  *  Purpose: Processes the WM_COMMAND message posted by the
  213.  *            Extended Help item of the Help menu
  214.  *
  215.  *  Usage:  Called from MainCommand when the Extended Help
  216.  *          menu item is selected
  217.  *
  218.  *  Method: Sends an HM_EXT_HELP message to the help
  219.  *          instance so that the default Extended Help is
  220.  *          displayed.
  221.  *
  222.  *  Returns:
  223.  *
  224. \****************************************************************/
  225. VOID  HelpExtended(MPARAM mp2)
  226. {
  227.  
  228.    /* this just displays the system extended help panel */
  229.    if(fHelpEnabled)
  230.    {
  231.       if((BOOL32)WinSendMsg(hwndHelpInstance, HM_EXT_HELP, NULL, NULL))
  232.       {
  233.          MessageBox(hwndMain,
  234.                     IDMSG_HELPDISPLAYERROR,
  235.                     MB_OK | MB_ERROR,
  236.                     FALSE);
  237.       }
  238.    }
  239. }   /* HelpExtended() */
  240.  
  241.  
  242. /****************************************************************\
  243.  *  Processes the Keys Help command from the menu bar
  244.  *--------------------------------------------------------------
  245.  *
  246.  *  Name:   HelpKeys(mp2)
  247.  *
  248.  *  Purpose: Processes the WM_COMMAND message posted by the
  249.  *            Keys Help item of the Help menu
  250.  *
  251.  *  Usage:  Called from MainCommand when the Keys Help
  252.  *          menu item is selected
  253.  *
  254.  *  Method: Sends an HM_KEYS_HELP message to the help
  255.  *          instance so that the default Keys Help is
  256.  *          displayed.
  257.  *
  258.  *  Returns:
  259.  *
  260. \****************************************************************/
  261. VOID  HelpKeys(MPARAM mp2)
  262. {
  263.  
  264.    /* this just displays the system keys help panel */
  265.    if(fHelpEnabled)
  266.    {
  267.       if(WinSendMsg(hwndHelpInstance, HM_KEYS_HELP, MPVOID, MPVOID))
  268.       {
  269.          MessageBox(hwndMain,
  270.                     IDMSG_HELPDISPLAYERROR,
  271.                     MB_OK | MB_ERROR,
  272.                     FALSE);
  273.       }
  274.    }
  275. }   /* HelpKeys() */
  276.  
  277.  
  278. /****************************************************************\
  279.  *  Processes the Index Help command from the menu bar
  280.  *--------------------------------------------------------------
  281.  *
  282.  *  Name:   HelpIndex(mp2)
  283.  *
  284.  *  Purpose: Processes the WM_COMMAND message posted by the
  285.  *            Index Help item of the Help menu
  286.  *
  287.  *  Usage:  Called from MainCommand when the Index Help
  288.  *          menu item is selected
  289.  *
  290.  *  Method: Sends an HM_INDEX_HELP message to the help
  291.  *          instance so that the default Index Help is
  292.  *          displayed.
  293.  *
  294.  *  Returns:
  295.  *
  296. \****************************************************************/
  297. VOID  HelpIndex(MPARAM mp2)
  298. {
  299.  
  300.    /* this just displays the system help index panel */
  301.    if(fHelpEnabled)
  302.    {
  303.       if(WinSendMsg(hwndHelpInstance, HM_HELP_INDEX, MPVOID, MPVOID))
  304.       {
  305.          MessageBox(hwndMain,
  306.                     IDMSG_HELPDISPLAYERROR,
  307.                     MB_OK | MB_ERROR,
  308.                     FALSE);
  309.       }
  310.    }
  311. }   /* HelpIndex() */
  312.  
  313.  
  314. /****************************************************************\
  315.  *  Processes the Tutorial Help command from the menu bar
  316.  *--------------------------------------------------------------
  317.  *
  318.  *  Name:   HelpTutorial(mp2)
  319.  *
  320.  *  Purpose: Processes the WM_COMMAND message posted by the
  321.  *            Tutorial Help item of the Help menu.  While the
  322.  *            standard template application does not include a
  323.  *            Tutorial menu item, you can add one if your
  324.  *            application has a tutorial.
  325.  *
  326.  *  Usage:  Called from MainCommand when the Tutorial Help
  327.  *          menu item is selected
  328.  *
  329.  *  Method:
  330.  *
  331.  *  Returns:
  332.  *
  333. \****************************************************************/
  334. VOID  HelpTutorial(MPARAM mp2)
  335. {
  336.  
  337.    /*--------------------------------------------------------------*\
  338.     *  Insert code for any tutorial here
  339.    \*--------------------------------------------------------------*/
  340.  
  341.  
  342. }   /* HelpTutorial() */
  343.  
  344.  
  345. /****************************************************************\
  346.  *  Processes the About command from the Help menu
  347.  *--------------------------------------------------------------
  348.  *
  349.  *  Name:   HelpAbout(mp2)
  350.  *
  351.  *  Purpose: Processes the WM_COMMAND message posted by the
  352.  *            About item of the Help menu
  353.  *
  354.  *  Usage:  Called from MainCommand when the About
  355.  *          menu item is selected
  356.  *
  357.  *  Method: Calls WinDlgBox to display the about box dialog.
  358.  *
  359.  *  Returns:
  360.  *
  361. \****************************************************************/
  362. VOID  HelpAbout(MPARAM mp2)
  363. {
  364.  
  365.    /* display the AboutBox dialog */
  366.    WinDlgBox(HWND_DESKTOP,
  367.              hwndMainFrame,
  368.              AboutBoxDlgProc,
  369.              0,
  370.              IDD_ABOUTBOX,
  371.              (PVOID)NULL);
  372. }   /* HelpAbout() */
  373.  
  374.  
  375. /****************************************************************\
  376.  *  Displays the help panel indicated
  377.  *--------------------------------------------------------------
  378.  *
  379.  *  Name:   DisplayHelpPanel(idPanel)
  380.  *
  381.  *  Purpose: Displays the help panel whose id is given
  382.  *
  383.  *  Usage:  Called whenever a help panel is desired to be
  384.  *          displayed, usually from the WM_HELP processing
  385.  *          of the dialog boxes
  386.  *
  387.  *  Method: Sends HM_DISPLAY_HELP message to the help instance
  388.  *
  389.  *  Returns:
  390.  *
  391. \****************************************************************/
  392. VOID DisplayHelpPanel(SHORT idPanel)  /* ID of the help panel to be displayed */
  393. {
  394.  
  395.    if(fHelpEnabled)
  396.    {
  397.       if(WinSendMsg(hwndHelpInstance,
  398.             HM_DISPLAY_HELP,
  399.             MPFROMLONG(MAKELONG(idPanel, NULL)),
  400.             MPFROMSHORT(HM_RESOURCEID)))
  401.       {
  402.          MessageBox(hwndMainFrame,
  403.                     IDMSG_HELPDISPLAYERROR,
  404.                     MB_OK | MB_ERROR,
  405.                     TRUE);
  406.       }
  407.    }
  408. }   /* DisplayHelpPanel() */
  409.  
  410.  
  411.  
  412. /****************************************************************\
  413.  *  Destroys the help instance
  414.  *--------------------------------------------------------------
  415.  *
  416.  *  Name:   DestroyHelpInstance(VOID)
  417.  *
  418.  *  Purpose: Destroys the help instance for the application
  419.  *
  420.  *  Usage:  Called after exit from message loop
  421.  *
  422.  *  Method: Calls WinDestroyHelpInstance() to destroy the
  423.  *          help instance
  424.  *
  425.  *  Returns:
  426.  *
  427. \****************************************************************/
  428. VOID DestroyHelpInstance(VOID)
  429. {
  430.  
  431.    if(hwndHelpInstance != NULLHANDLE)
  432.    {
  433.       WinDestroyHelpInstance(hwndHelpInstance);
  434.    }
  435. }   /* DestroyHelpInstance() */
  436.  
  437.  
  438. /****************************************************************\
  439.  *  Dialog procedure for the About dialog box
  440.  *--------------------------------------------------------------
  441.  *
  442.  *  Name:   AboutBoxDlgProc(hwnd, msg, mp1, mp2)
  443.  *
  444.  *  Purpose: Processes all messages sent to the About Box
  445.  *
  446.  *  Usage:  Called for each message sent to the About Box
  447.  *          dialog box.
  448.  *
  449.  *  Method: the about box only has a button control so this
  450.  *          routine only processes WM_COMMAND messages.  Any
  451.  *          WM_COMMAND posted must have come from the Ok
  452.  *          button so we dismiss the dialog upon receiving it.
  453.  *
  454.  *  Returns: Dependent upon message sent
  455.  *
  456. \****************************************************************/
  457. MRESULT EXPENTRY AboutBoxDlgProc(HWND   hwnd,      /* handle of window */
  458.                                  ULONG  msg,     /* id of message */
  459.                                  MPARAM mp1,     /* first message parameter */
  460.                                  MPARAM mp2)     /* second message parameter */
  461. {
  462.    switch(msg)
  463.    {
  464.       case WM_COMMAND:
  465.          /* no matter what the command, close the dialog */
  466.          WinDismissDlg(hwnd, TRUE);
  467.          break;
  468.  
  469.       default:
  470.          return(WinDefDlgProc(hwnd, msg, mp1, mp2));
  471.          break;
  472.    }
  473.  
  474.    return (MRFROMLONG(0));
  475.  
  476. }   /* AboutBoxWndProc() */
  477.