HOWTO: Add a Hook Function to a Common Dialog Box

ID: Q86721

The information in this article applies to:

• Microsoft Windows Software Development Kit (SDK)
• Microsoft Win32 Software Development Kit (SDK)

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;
   }

Keywords          : kbCmnDlg kbNTOS kbGrpUser kbWinOS 
Issue type        : kbhowto

Last Reviewed: December 18, 1998