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