INFO: Context-Sensitive Help in a Dialog Box Through F1

• Microsoft Windows Software Development Kit (SDK) 3.1

SUMMARY

In an application developed with Windows version 3.0 and later, to implement the ability to request context-sensitive help by pressing the F1 key in a dialog box, it is necessary to install a message filter.

This article describes how to install the message filter. In particular, it describes code that you can add to the Generic sample application (included with the Windows Software Development Kit) to install a message filter that would detect F1 keystrokes in the About Generic modal dialog box.

MORE INFORMATION

Detecting F1 Keystrokes in a Dialog Box

Installing a Filter Function

Sample Code

1. Define a private message that the filter function can post to the application. For example:

   
      #define PM_CALLHELP  WM_USER+1000
                                     // wParam and lParam can be used to
                                     // pass context information 




2. Define global variables:

   
      FARPROC lpfnFilterProc;        // Our filter function
         HHOOK hHook;                   // hook handle 




3. Add a filter function to the C-language source file. For example:

   
      /*--------------------------    FilterFunc -------------------------*/ 
      // 
      //   PARAMETERS:
      // 
      //      nCode : Specifies the type of message being processed. It will
      //              be either MSGF_DIALOGBOX, MSGF_MENU, or less than 0.
      // 
      //      wParam: specifies a NULL value
      // 
      //      lParam: a FAR pointer to a MSG structure
      // 
      // 
      //   GLOBAL VARIABLES USED:
      // 
      //      hHook
      // 
      // 
      //   NOTES:
      // 
      //     If (nCode < 0), return CallNextHookEx IMMEDIATELY.
      // 
      //     If (MSGF_DIALOGBOX==nCode), set the local variable ptrMsg to
      //     point to the message structure. If this message is an F1
      //     keystroke, ptrMsg-&gt;hwnd will contain the HWND for the dialog
      //     control that the user wants help information on. Post a private
      //     message to the application, then return 1L to indicate that
      //     this message was handled.
      // 
      //     When the application receives the private message, it can call
      //     WinHelp. WinHelp must NOT be called directly from the
      //     FilterFunc() routine.
      // 
      //     In this example, post a private PM_CALLHELP message to the
      //     dialog box. wParam and lParam can be used to pass context
      //     information.
      // 
      //     If the message is not an F1 keystroke, or if nCode is
      //     MSGF_MENU, we return 0L to indicate that we did not process
      //     this message.
      // 
      // 
   
      DWORD CALLBACK FilterFunc(nCode, wParam, lParam)
      int   nCode;
      WORD  wParam;
      DWORD lParam;
      {
         MSG FAR * ptrMsg;
   
         if (nCode >= 0)                         // MUST return CallNextHookEx
         {
            if (MSGF_DIALOGBOX == nCode)
            {
               ptrMsg = (MSG FAR *)lParam;
   
               if ((WM_KEYDOWN == ptrMsg->message)
                      && (VK_F1 == ptrMsg->wParam))
               {
                  // Use PostMessage here to post an application-defined
                  // message to the application. Here is one possible call:
                  PostMessage(GetParent(ptrMsg->hwnd),
                                         PM_CALLHELP, ptrMsg->hwnd, 0L);
                  return 1L;                       // Handled it
               }
            }
         }
         return CallNextHookEx(hHook, nCode, wParam, lParam);
      }
      /*--------------------- end FilterFunc  ----------------------------*/  




4. Export the filter function in the module definition file.



5. Before calling DialogBox(), set the hook. After DialogBox() returns, unhook the hook. For example, the About Generic dialog box could be called as follows:

   
      case IDM_ABOUT:
        lpProcAbout    = MakeProcInstance(About, hInst);
        lpfnFilterProc = MakeProcInstance(FilterFunc, hInst);
        hHook    = SetWindowsHookEx(WH_MSGFILTER,
                                          lpfnFilterProc,
                                          hInst,
                                          NULL);
   
        DialogBox(hInst, "AboutBox", hWnd, lpProcAbout);
   
        UnhookWindowsHookEx(hHook);
        FreeProcInstance(lpfnFilterProc);
        FreeProcInstance(lpProcAbout);
   
        break; 




6. Make the application respond to the private message by calling WinHelp.

REFERENCES

Additional query words:

Keywords : kbcode kb16bitonly kbDlg kbSDKPlatform kbGrpUser kbUser
Version : WINDOWS:3.1
Platform : WINDOWS
Issue type : kbinfo