This documentation is archived and is not being maintained.


Displays a modal property sheet.

virtual INT_PTR DoModal( );

IDOK or IDCANCEL if the function was successful; otherwise 0 or -1. If the property sheet has been established as a wizard (see SetWizardMode), DoModal returns either ID_WIZFINISH or IDCANCEL.

The return value corresponds to the ID of the control that closed the property sheet. After this function returns, the windows corresponding to the property sheet and all the pages will have been destroyed. The objects themselves will still exist. Typically, you will retrieve data from the CPropertyPage objects after DoModal returns IDOK.

To display a modeless property sheet, call Create instead.


The first time a property page is created from its corresponding dialog resource, it may cause a first-chance exception. This is a result of the property page changing the style of the dialog resource to the required style prior to creating the page. Because resources are generally read-only, this causes an exception. The exception is handled by the system, and a copy of the modified resource is made automatically by the system. The first-chance exception can thus be ignored.


Because this exception must be handled by the operating system, do not wrap calls to CPropertySheet::DoModal with a C++ try/catch block in which the catch handles all exceptions, for example, catch (...). This will handle the exception intended for the operating system, causing unpredictable behavior. Using C++ exception handling with specific exception types or using structured exception handling where the Access Violation exception is passed through to the operating system is safe, however.

See the example for CPropertySheet::AddPage.