WinAssociateHelpInstance

This function associates the specified instance of the Help Manager with the window chain of the specified application window.

Syntax

WinAssociateHelpInstance(hwndHelpInstance, hwndApp);

Parameters

hwndHelpInstance (HWND) - input

Handle of an instance of the Help Manager.

This is the handle returned by the WinCreateHelpInstance call.

NULLHANDLE

Disassociates an instance of the Help Manager from a window chain when the instance has been destroyed.

Other

The handle of an instance of the Help Manager to be associated with the application window chain.

hwndApp (HWND) - input

Handle of an application window.

The handle of the application window with which the instance of the Help Manager will be associated. The instance of the Help Manager is associated with the application window and any of its children or owned windows.

Returns

rc (BOOL) - returns

Success indicator.

TRUE

Successful completion

FALSE

Error occurred.

Remarks

In order to provide help, the application must associate an instance of the Help Manager with a chain of application windows. This association lets the Help Manager know which instance should provide the help function.

The Help Manager traces the window chain, starting from the window where help is requested. The application window in the chain with the associated help instance will be the one with which the Help Manager communicates and next to which the help window is positioned, unless a HM_SET_ACTIVE_WINDOW message is sent to the Help Manager. If the HM_SET_ACTIVE_WINDOW message is sent to the Help Manager, the active window parameter is the window with which the Help Manager communicates. The Help Manager positions the help window next to the window specified as the relative window.

Example Code

This example shows a typical main function for an application which uses help. Following creation of the main application window the Help Manager is initialized and associated with the window. The help table is defined in the application's resources. When the window is destroyed, terminating the application, the help instance is also destroyed.

#define INCL=_WIN
#include <os2.h>

#define IDHT_APPLICATION        100     /* id of HELP TABLE in resource file */

main( int argc, char *argv[], char *envp[] )
{
   HAB  hab = WinInitialize( 0 );
   HMQ  hmq = WinCreateMsgQueue( hab, 0 );
   HWND hwnd;
   HWND hwndClient;
   HWND hwndHelp;
   QMSG qmsg;
   ULONG flStyle;
   HELPINIT helpinit;

   /* Setup the help initialization structure */
   helpinit.cb = sizeof( HELPINIT );
   helpinit.ulReturnCode =  0L;
   helpinit.pszTutorialName =  (PSZ)NULL;
   /* Help table in application resource */
   helpinit.phtHelpTable = (PHELPTABLE)MAKEULONG( IDHT_APPLICATION, 0xffff );
   helpinit.hmodHelpTableModule = NULLHANDLE;
   /* Default action bar and accelerators */
   helpinit.hmodAccelActionBarModule = NULLHANDLE;
   helpinit.idAccelTable = 0;
   helpinit.idActionBar = 0;
   helpinit.pszHelpWindowTitle = "APPNAME HELP";
   helpinit.fShowPanelId = CMIC_SHOW_PANEL_ID;
   helpinit.pszHelpLibraryName = "APPNAME.HLP";

   /* Register the class */
   if( WinRegisterClass( ... ) )
   {
      /* create the main window */
      flStyle = FCF_STANDARD;
      hwnd = WinCreateStdWindow( ... );

      if( hwnd )
      {
         /* Create and associate the help instance */
         hwndHelp = WinCreateHelpInstance( hab, &helpinit );

         if( hwndHelp && WinAssociateHelpInstance( hwndHelp, hwnd ) )
         {
            /* Process messages */
            while( WinGetMsg( hab, &qmsg, NULLHANDLE, 0, 0 ) )
            {
               WinDispatchMsg( hab, &qmsg );
            } /* endwhile */
         }

         /* Remove help instance - note: add                    */
         /*     WinAssociateHelpInstance( NULLHANDLE, hwnd );      */
         /* to WM_DESTROY processing to remove the association. */
         WinDestroyHelpInstance( hwndHelp );
      }
   }

   /* finish the cleanup and exit */
   WinDestroyMsgQueue( hmq );
   WinTerminate( hab );
}

Definition

#define INCL_WINHELP /* Or use INCL_WIN, INCL_PM, */
#include <os2.h>

HWND    hwndHelpInstance;  /*  Handle of an instance of the Help Manager. */
HWND    hwndApp;           /*  Handle of an application window. */
BOOL    rc;                /*  Success indicator. */

rc = WinAssociateHelpInstance(hwndHelpInstance,
       hwndApp);

Related Functions

• WinAssociateHelpInstance
• WinCreateHelpInstance
• WinCreateHelpTable
• WinDestroyHelpInstance
• WinLoadHelpTable
• WinQueryHelpInstance

Related Messages

• HM_SET_ACTIVE_WINDOW