HOWTO: Use DWL_MSGRESULT in Property Sheets & Wizard Controls

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

SUMMARY

Each page in a property sheet or wizard control is an application-defined modeless dialog box that manages the control windows used to view and edit the properties of an item. Applications provide the dialog box template used to create each page as well as the dialog box procedure.

A property sheet or wizard control sends notification messages to the dialog box procedure for a page when the page is gaining or losing the focus and when the user clicks OK, Cancel, or other buttons. The notifications are sent in the form of WM_NOTIFY messages. The dialog box procedure(s) for the corresponding page(s) should use the SetWindowLong() function to set the DWL_MSGRESULT value of the page dialog box to specify the return value from the dialog box procedure to prevent or accept the change. After doing so, the dialog box procedure must return TRUE in response to processing the WM_NOTIFY message. If it does not return TRUE, the return value set in the DWL_MSGRESULT index using the SetWindowLong() function is ignored by the property sheet or wizard control.

The call to SetWindowLong should be the last thing the page dialog box procedure does before returning from the procedure. This call should be last because there is a possibility that another function call could cause another SetWindowLong with DWL_MSGRESULT to be called, which would overwrite what was already stored in DWL_MSGRESULT. Any message sent to the dialog box procedure will cause DWL_MSGRESULT to be an undefined value.

MORE INFORMATION

Dialog box procedures return a BOOL value (TRUE or FALSE). This return value indicates to the caller of the dialog box function that the dialog box function either handled the message that it received or did not handle it. When the dialog box function returns FALSE, it is indicating that it did not handle the message it received. When the dialog box handles the message and generates a return value, it typically sets the DWL_MSGRESULT index of the dialog box with the return value.

The dialog box function of the property sheet or wizard page handles messages (WM_NOTIFY) sent by the property sheet or wizard control. The property sheet or wizard control determines whether the page that received the message processed the message or not by checking the return value from the call to SendMessage(). If the return value is FALSE, the control goes ahead and does what needs to be done by default. But if the return value is TRUE, the control checks for the return value by looking at the value stored in the DWL_MSGRESULT index of that page.

For example, the dialog box function of a property page might trap the PSN_SETACTIVE notification to prevent it from being activated under certain circumstances. In this case, the page dialog box function uses the SetWindowLong() function to set the DWL_MSGRESULT value to -1. If the dialog box function does not return True after setting the DWL_MSGRESULT, the property sheet control that sent the message completely ignores the return value because it assumes there is no return value.

Additional query words:

Keywords : kbCtrl kbNTOS351 kbNTOS400 kbWinOS2000 kbPropSheet kbSDKWin32 kbGrpUser kbWinOS95 kbWinOS98
Version : WINDOWS:
Platform : WINDOWS
Issue type : kbhowto