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