Return to sty_help.c CVS log

Up to [OS/2 SDKs] / os232sdk / toolkt20 / c / samples / style

Microsoft OS/2 SDK 2.0 05-30-1990

/*==============================================================*\
 *  Help.c - routines for the help manager interface
 *      Created 1990, Microsoft, IBM  Corp.
 *--------------------------------------------------------------
 *
 *  This module contains all the routines for interfacing with
 *  the IPF help manager.
 *
 *--------------------------------------------------------------
 *
 *  This source file contains the following functions:
 *
 *          InitHelp()
 *          HelpHelpForHelp(mp2)
 *          HelpExtended(mp2)
 *          HelpKeys(mp2)
 *          HelpIndex(mp2)
 *          HelpTutorial(mp2)
 *          HelpAbout(mp2)
 *          DisplayHelpPanel(idPanel)
 *          DestroyHelpInstance()
 *
\*==============================================================*/

/*--------------------------------------------------------------*\
 *  Include files, macros, defined constants, and externs
\*--------------------------------------------------------------*/


/* If DEBUG is defined, then the help panels will display their
 *  id values on their title bar.  This is useful for determining
 *  which help panels are being shown for each dialog item.  When
 *  the DEBUG directive is not defined, then the panel ids are not
 *  displayed.
 */

/*
#define  DEBUG
*/

#define  INCL_WINHELP

#include <os2.h>
#include <string.h>
#include "sty_main.h"
#include "sty_xtrn.h"
#include "sty_dlg.h"
#include "sty_help.h"

#define HELPLIBRARYNAMELEN  20

/*--------------------------------------------------------------*\
 *  Global variables
\*--------------------------------------------------------------*/
static HWND hwndHelpInstance;
static CHAR szLibName[HELPLIBRARYNAMELEN];
static CHAR szWindowTitle[HELPLIBRARYNAMELEN];


/*--------------------------------------------------------------*\
 *  Entry point declarations
\*--------------------------------------------------------------*/
MRESULT EXPENTRY AboutBoxDlgProc(HWND hwnd, USHORT msg,
                                 MPARAM mp1, MPARAM mp2);


/****************************************************************\
 *  Routine for initializing the help manager
 *--------------------------------------------------------------
 *
 *  Name:   InitHelp()
 *
 *  Purpose: Initializes the IPF help facility
 *
 *  Usage:  Called once during initialization of the program
 *
 *  Method: Initializes the HELPINIT structure and creates the
 *          help instance.  If successful, the help instance
 *          is associated with the main window
 *
 *  Returns:
 *
\****************************************************************/
VOID InitHelp(VOID)
{
    HELPINIT hini;

    /* if we return because of an error, Help will be disabled */
    fHelpEnabled = FALSE;

    /* inititalize help init structure */
    hini.cb = sizeof(HELPINIT);
    hini.ulReturnCode = NULL;

    hini.pszTutorialName = (PSZ)NULL;   /* if tutorial added, add name here */

    hini.phtHelpTable = (PHELPTABLE)MAKELONG(STYLE_HELP_TABLE, 0xFFFF);
    hini.hmodHelpTableModule = NULL;
    hini.hmodAccelActionBarModule = NULL;
    hini.idAccelTable = NULL;
    hini.idActionBar = NULL;

    if(!WinLoadString(hab,
                      NULL,
                      IDS_HELPWINDOWTITLE,
                      HELPLIBRARYNAMELEN,
                      (PSZ)szWindowTitle))  {

        MessageBox(hwndMain, IDMSG_CANNOTLOADSTRING, MB_OK | MB_ERROR, FALSE);
        return;
    }

    hini.pszHelpWindowTitle = (PSZ)szWindowTitle;

    /* if debugging, show panel ids, else don't */
#ifdef DEBUG
    hini.usShowPanelId = CMIC_SHOW_PANEL_ID;
#else
    hini.usShowPanelId = CMIC_HIDE_PANEL_ID;
#endif

    if(!WinLoadString(hab,
                      NULL,
                      IDS_HELPLIBRARYNAME,
                      HELPLIBRARYNAMELEN,
                      (PSZ)szLibName))  {

        MessageBox(hwndMain, IDMSG_CANNOTLOADSTRING, MB_OK | MB_ERROR, FALSE);
        return;
    }

    hini.pszHelpLibraryName = (PSZ)szLibName;

    /* creating help instance */
    hwndHelpInstance = WinCreateHelpInstance(hab, &hini);

    if(!hwndHelpInstance || hini.ulReturnCode)  {
        MessageBox(hwndMainFrame,
                   IDMSG_HELPLOADERROR,
                   MB_OK | MB_ERROR,
                   TRUE);
        return;
    }

    /* associate help instance with main frame */
    if(!WinAssociateHelpInstance(hwndHelpInstance, hwndMainFrame)) {
        MessageBox(hwndMainFrame,
                   IDMSG_HELPLOADERROR,
                   MB_OK | MB_ERROR,
                   TRUE);
        return;
    }

    /* help manager is successfully initialized so set flag to TRUE */
    fHelpEnabled = TRUE;

}   /* InitHelp() */


/****************************************************************\
 *  Processes the Help for Help command from the menu bar
 *--------------------------------------------------------------
 *
 *  Name:   HelpHelpForHelp(mp2)
 *
 *  Purpose: Processes the WM_COMMAND message posted by the
 *            Help for Help item of the Help menu
 *
 *  Usage:  Called from MainCommand when the Help for Help
 *          menu item is selected
 *
 *  Method: Sends an HM_DISPLAY_HELP message to the help
 *          instance so that the default Help For Help is
 *          displayed.
 *
 *  Returns:
 *
\****************************************************************/
VOID  HelpHelpForHelp(mp2)
MPARAM mp2;     /* second parameter of WM_COMMAND message */
{

    /* this just displays the system help for help panel */
    if(fHelpEnabled)
        if(WinSendMsg(hwndHelpInstance, HM_DISPLAY_HELP, NULL, NULL))
            MessageBox(hwndMain,
                       IDMSG_HELPDISPLAYERROR,
                       MB_OK | MB_ERROR,
                       FALSE);

    /* This routine currently doesn't use the mp2 parameter but       *\
     *  it is referenced here to prevent an 'Unreferenced Parameter'
    \*  warning at compile time.                                      */
    mp2;

}   /* HelpHelpForHelp() */


/****************************************************************\
 *  Processes the Extended Help command from the menu bar
 *--------------------------------------------------------------
 *
 *  Name:   HelpExtended(mp2)
 *
 *  Purpose: Processes the WM_COMMAND message posted by the
 *            Extended Help item of the Help menu
 *
 *  Usage:  Called from MainCommand when the Extended Help
 *          menu item is selected
 *
 *  Method: Sends an HM_EXT_HELP message to the help
 *          instance so that the default Extended Help is
 *          displayed.
 *
 *  Returns:
 *
\****************************************************************/
VOID  HelpExtended(mp2)
MPARAM mp2;     /* second parameter of WM_COMMAND message */
{

    /* this just displays the system extended help panel */
    if(fHelpEnabled)
        if(WinSendMsg(hwndHelpInstance, HM_EXT_HELP, NULL, NULL))
            MessageBox(hwndMain,
                       IDMSG_HELPDISPLAYERROR,
                       MB_OK | MB_ERROR,
                       FALSE);

    /* This routine currently doesn't use the mp2 parameter but       *\
     *  it is referenced here to prevent an 'Unreferenced Parameter'
    \*  warning at compile time.                                      */
    mp2;

}   /* HelpExtended() */


/****************************************************************\
 *  Processes the Keys Help command from the menu bar
 *--------------------------------------------------------------
 *
 *  Name:   HelpKeys(mp2)
 *
 *  Purpose: Processes the WM_COMMAND message posted by the
 *            Keys Help item of the Help menu
 *
 *  Usage:  Called from MainCommand when the Keys Help
 *          menu item is selected
 *
 *  Method: Sends an HM_KEYS_HELP message to the help
 *          instance so that the default Keys Help is
 *          displayed.
 *
 *  Returns:
 *
\****************************************************************/
VOID  HelpKeys(mp2)
MPARAM mp2;     /* second parameter of WM_COMMAND message */
{

    /* this just displays the system keys help panel */
    if(fHelpEnabled)
        if(WinSendMsg(hwndHelpInstance, HM_KEYS_HELP, NULL, NULL))
            MessageBox(hwndMain,
                       IDMSG_HELPDISPLAYERROR,
                       MB_OK | MB_ERROR,
                       FALSE);


    /* This routine currently doesn't use the mp2 parameter but       *\
     *  it is referenced here to prevent an 'Unreferenced Parameter'
    \*  warning at compile time.                                      */
    mp2;

}   /* HelpKeys() */


/****************************************************************\
 *  Processes the Index Help command from the menu bar
 *--------------------------------------------------------------
 *
 *  Name:   HelpIndex(mp2)
 *
 *  Purpose: Processes the WM_COMMAND message posted by the
 *            Index Help item of the Help menu
 *
 *  Usage:  Called from MainCommand when the Index Help
 *          menu item is selected
 *
 *  Method: Sends an HM_INDEX_HELP message to the help
 *          instance so that the default Index Help is
 *          displayed.
 *
 *  Returns:
 *
\****************************************************************/
VOID  HelpIndex(mp2)
MPARAM mp2;     /* second parameter of WM_COMMAND message */
{

    /* this just displays the system help index panel */
    if(fHelpEnabled)
        if(WinSendMsg(hwndHelpInstance, HM_HELP_INDEX, NULL, NULL))
            MessageBox(hwndMain,
                       IDMSG_HELPDISPLAYERROR,
                       MB_OK | MB_ERROR,
                       FALSE);


    /* This routine currently doesn't use the mp2 parameter but       *\
     *  it is referenced here to prevent an 'Unreferenced Parameter'
    \*  warning at compile time.                                      */
    mp2;

}   /* HelpIndex() */


/****************************************************************\
 *  Processes the Tutorial Help command from the menu bar
 *--------------------------------------------------------------
 *
 *  Name:   HelpTutorial(mp2)
 *
 *  Purpose: Processes the WM_COMMAND message posted by the
 *            Tutorial Help item of the Help menu.  While the
 *            standard template application does not include a
 *            Tutorial menu item, you can add one if your
 *            application has a tutorial.
 *
 *  Usage:  Called from MainCommand when the Tutorial Help
 *          menu item is selected
 *
 *  Method:
 *
 *  Returns:
 *
\****************************************************************/
VOID  HelpTutorial(mp2)
MPARAM mp2;     /* second parameter of WM_COMMAND message */
{

   /*--------------------------------------------------------------*\
    *  Insert code for any tutorial here
   \*--------------------------------------------------------------*/


    /* This routine currently doesn't use the mp2 parameter but       *\
     *  it is referenced here to prevent an 'Unreferenced Parameter'
    \*  warning at compile time.                                      */
    mp2;

}   /* HelpTutorial() */

/****************************************************************\
 *  Processes the About command from the Help menu
 *--------------------------------------------------------------
 *
 *  Name:   HelpAbout(mp2)
 *
 *  Purpose: Processes the WM_COMMAND message posted by the
 *            About item of the Help menu
 *
 *  Usage:  Called from MainCommand when the About
 *          menu item is selected
 *
 *  Method: Calls WinDlgBox to display the about box dialog.
 *
 *  Returns:
 *
\****************************************************************/
VOID  HelpAbout(mp2)
MPARAM mp2;     /* second parameter of WM_COMMAND message */
{
    /* display the AboutBox dialog */
    WinDlgBox(hwndMain,
              hwndMain,
              (PFNWP)AboutBoxDlgProc,
              NULL,
              IDD_ABOUTBOX,
              (PVOID)NULL);

    /* This routine currently doesn't use the mp2 parameter but       *\
     *  it is referenced here to prevent an 'Unreferenced Parameter'
    \*  warning at compile time.                                      */
    mp2;

}   /* HelpAbout() */


/****************************************************************\
 *  Displays the help panel indicated
 *--------------------------------------------------------------
 *
 *  Name:   DisplayHelpPanel(idPanel)
 *
 *  Purpose: Displays the help panel whose id is given
 *
 *  Usage:  Called whenever a help panel is desired to be
 *          displayed, usually from the WM_HELP processing
 *          of the dialog boxes
 *
 *  Method: Sends HM_DISPLAY_HELP message to the help instance
 *
 *  Returns:
 *
\****************************************************************/
VOID DisplayHelpPanel(idPanel)
SHORT idPanel;      /* ID of the help panel to be displayed */
{

    if(fHelpEnabled)
        if(WinSendMsg(hwndHelpInstance,
                      HM_DISPLAY_HELP,
                      MPFROM2SHORT(idPanel, NULL),
                      MPFROMSHORT(HM_RESOURCEID)))

            MessageBox(hwndMainFrame,
                       IDMSG_HELPDISPLAYERROR,
                       MB_OK | MB_ERROR,
                       TRUE);


}   /* DisplayHelpPanel() */



/****************************************************************\
 *  Destroys the help instance
 *--------------------------------------------------------------
 *
 *  Name:   DestroyHelpInstance(VOID)
 *
 *  Purpose: Destroys the help instance for the application
 *
 *  Usage:  Called after exit from message loop
 *
 *  Method: Calls WinDestroyHelpInstance() to destroy the
 *          help instance
 *
 *  Returns:
 *
\****************************************************************/
VOID DestroyHelpInstance(VOID)
{
    if(hwndHelpInstance)  {
        WinDestroyHelpInstance(hwndHelpInstance);
    }

}   /* DestroyHelpInstance() */

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.