LONG CommonPropertySheetUI(
| HWND hWndOwner, | |
| PFNPROPSHEETUI pfnPropSheetUI, | |
| LPARAM lParam, | |
| LPDWORD pResult | |
| ); |
CommonPropertySheetUI manages and displays a property sheet.
Parameters
hWndOwner
Window handle for the owner of the property sheet. This parameter can be null.
pfnPropSheetUI
Pointer to a callback function of type PFNPROPSHEETUI.
lParam
Specifies the parameter that is passed to the function to which pfnPropSheetUI points when it is called by the CPSUI.
pResult
Pointer to a DWORD that receives the final result of the function to which pfnPropSheetUI points when it is called. Specifically, the Result field of the PROPSHEETUI_INFO structure is copied into pResult if an error is not returned; otherwise, pResult is set to null.
Return Value
CommonPropertySheetUI returns one of the following values:
| Return Value | Description |
| CPSUI_CANCEL | The property sheet was not displayed because there were no pages. |
| CPSUI_OK | The function succeeded. |
| CPSUI_RESTARTWINDOWS | The function succeeded. The property sheet was displayed, and the end-user changed a selection that requires the login session to be restarted in order for the change to take effect. |
| CPSUI_REBOOTSYSTEM | The function succeeded. The property sheet was displayed, and the end-user changed a selection that requires the system to be rebooted in order for the change to take effect. |
| ERR_CPSUI_Xxx | The property sheet was not displayed due to the error specified by the return error code. These error code values are always less than zero. |
Comments
CommonPropertySheetUI is the main entry point for the CPSUI. An application calls this function to have the CPSUI manage and display a property sheet.
The function to which pfnPropSheetUI points is a caller-defined function in which the caller requests the CPSUI to add pages to the property sheet. The CPSUI calls this function as follows:
PROPSHEETUI_INFO PSUIInfo;
pfnPropSheetUI(&PSUIInfo, lParam);
When an end-user closes the property sheet by selecting OK or Cancel, CommonPropertySheetUI returns the appropriate CPSUI_Xxx value to the original caller.
If the function to which pfnPropSheetUI points returns a LONG value greater than zero, the CPSUI displays the property sheet dialog boxes. When an end-user closes the property sheet by selecting OK or Cancel, CommonPropertySheetUI returns one of CPSUI_OK, CPSUI_RESTARTWINDOWS, or CPSUI_REBOOTSYSTEM. If the callback returns a LONG value that is equal to or less than zero, there were no pages on the property sheet or an error was encountered. In this situation, the CPSUI did not display the property sheet and CommonPropertySheetUI returns CPSUI_CANCEL or ERR_CPSUI_Xxx.
When the last call to pfnPropSheetUI() returns, the value in the Result field of PROPSHEETUI_INFO is copied into the DWORD to which pResult points. The pResult parameter is set only when CommonPropertySheetUI does not return ERR_CPSUI_Xxx. CommonPropertySheetUI does not return the last DWORD result of pfnPropSheet() if pResult is null.
See Also