Export (0) Print
Expand All

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:

>=1Changes were saved by the user.
0No changes were saved by the user.
-1An 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 codeDescription
ID_PSREBOOTSYSTEM

A page sent the PSM_REBOOTSYSTEM message to the property sheet. The computer must be restarted for the user's changes to take effect.

ID_PSRESTARTWINDOWS

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.

Note  The following remarks refer only to wizards that do not use the Aero wizard style (PSH_AEROWIZARD) or non-wizard property sheets.

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 2000 Professional [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Header

Prsht.h

Library

Comctl32.lib

DLL

Comctl32.dll

Unicode and ANSI names

PropertySheetW (Unicode) and PropertySheetA (ANSI)

 

 

Community Additions

ADD
Show:
© 2014 Microsoft