PropertySheet function
Creates a property sheet and adds the pages defined in the specified property sheet header structure.
Syntax
INT_PTR PropertySheet( LPCPROPSHEETHEADER lppsph );
Parameters
- lppsph
-
Type: LPCPROPSHEETHEADER
Pointer to a PROPSHEETHEADER structure that defines the frame and pages of a property sheet.
Return value
Type: INT_PTR
For modal property sheets, the return value is as follows:
| >=1 | Changes were saved by the user. |
| 0 | No changes were saved by the user. |
| -1 | An error occurred. |
For modeless property sheets, the return value is the property sheet's window handle.
The following return values have a special meaning.
| Return code | Description |
|---|---|
|
A page sent the PSM_REBOOTSYSTEM message to the property sheet. The computer must be restarted for the user's changes to take effect. |
|
A page sent the PSM_RESTARTWINDOWS message to the property sheet. Windows must be restarted for the user's changes to take effect. |
Remarks
To retrieve extended error information, call GetLastError.
If you attempt to add more than 99 pages to a property sheet, this function will fail, but with no indication of the cause of the error: PropertySheet returns a value of -1, but GetLastError returns 0.
By default, the PropertySheet function creates a modal dialog box. If the dwFlags member of the PROPSHEETHEADER structure specifies the PSH_MODELESS flag, PropertySheet creates a modeless dialog box and returns immediately after it is created. In this case, the PropertySheet return value is the window handle to the modeless dialog box.
For a modeless property sheet, your message loop should use PSM_ISDIALOGMESSAGE to pass messages to the property sheet dialog box. Your message loop should use PSM_GETCURRENTPAGEHWND to determine when to destroy the dialog box. When the user clicks the OK or Cancel button, PSM_GETCURRENTPAGEHWND returns NULL. You can then use the DestroyWindow function to destroy the dialog box.
Version 5.80. The PropertySheet return value carries different information for modal and modeless property sheets. In some cases, modeless property sheets might need the information they would have received from PropertySheet if they had been modal. In particular, they may need to know whether ID_PSREBOOTSYSTEM or ID_PSRESTARTWINDOWS would have been returned. A modeless property sheet can retrieve the value that a modal property sheet would have received from PropertySheet by waiting until PSM_GETCURRENTPAGEHWND returns NULL and then sending a PSM_GETRESULT message.
Requirements
|
Minimum supported client |
Windows Vista [desktop apps only] |
|---|---|
|
Minimum supported server |
Windows Server 2003 [desktop apps only] |
|
Header |
|
|
Library |
|
|
DLL |
|
|
Unicode and ANSI names |
PropertySheetW (Unicode) and PropertySheetA (ANSI) |