Adding a Hook Function to a Common Dialog Box

• Microsoft Windows Software Development Kit (SDK) versions 3.1
• Microsoft Win32 Application Programming Interface (API) included with:

      - Microsoft Windows NT versions 3.5 and 3.51
      - Microsoft Windows 95 version 4.0
  

SUMMARY

Many applications developed for the Microsoft Windows environment using dialog boxes from the common dialogs library (COMMDLG.DLL) require hook functions. A hook function for one of the common dialog boxes is similar to a subclass procedure for a standard Window control, such as an edit control. Through a hook function, an application can process all messages addressed to the dialog box. The text below discusses the steps required to implement a hook function with a common dialog box.

A hook function is most often used in conjunction with a custom dialog template. For details using a custom dialog template with one of the common dialog boxes, query on the following words in the Microsoft Knowledge Base:

   steps add custom template

MORE INFORMATION

The hook function receives all messages addressed to a common dialog box. With the exception of the WM_INITDIALOG message, the hook function receives messages before its associated common dialog box does. If the hook function processes a message completely, it returns TRUE. If the common dialog box must provide default processing for a message, the hook function returns FALSE.

CDDEMO, one of the advanced sample applications provided with version 3.1 of the Microsoft Windows Software Development Kit (SDK), demonstrates adding a hook function to the File Open dialog box. The eight steps involved in this process are as follows:

1. Add the standard common dialog box to the application without the hook function.

2. In the application's module definition (DEF) file, list the hook procedure name (for example, MyHookProc) in the EXPORTS section.

3. Define a FARPROC variable (for example, lpfnHookProc)

4. In the application, before completing the OPENFILENAME data structure, call the MakeProcInstance function to create a procedure instance address for the hook procedure.

5. Set the lpfnHook member of the OPENFILENAME data structure to the procedure address of the hook function.

6. Specify OFN_ENABLEHOOK as one of the initialization flags in the Flags member of the OPENFILENAME structure.

7. Code the hook function to process messages as required. A sample hook function follows below.

8. After the user dismisses the common dialog box, call the FreeProcInstance function to free the procedure instance address.

   BOOL FAR PASCAL MyHookProc(HWND hDlg, unsigned message,
                              WORD wParam, LONG lParam)
   {
      switch (message)
      {
         case WM_INITDIALOG:
            OutputDebugString("Hello hook function!");
            return TRUE;

         case WM_COMMAND:
            switch(wParam)
            {
               case IDD_MYNEWCONTROL:
               // Perform appropriate processing here...
                  return TRUE;

               default:
                  break;
            }
            break;

         default:
            break;
      }
      return FALSE;
   }