CPropertySheet::DoModal

Displays a modal property sheet.

virtual INT_PTR DoModal();

Return Value

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.

Remarks

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.

When a property page is created from its corresponding dialog resource, it can cause a first-chance exception. This results from the property page changing the style of the dialog resource to the required style before the page is created. Because resources are generally read-only, this causes an exception. The system handles the exception, and makes a copy of the modified resource. The first-chance exception can therefore be ignored.

ملاحظة

This exception must be handled by the operating system if you are compiling with the asynchronous exception handling model. For more information about exception handling models, see /EH (Exception Handling Model). In this case, do not wrap calls to CPropertySheet::DoModal with a C++ try-catch block in which the catch handles all exceptions, for example, catch (...). This block would handle the exception intended for the operating system, and cause unpredictable behavior. However, you can safely use C++ exception handling with specific exception types or structured exception handling where the Access Violation exception is passed through to the operating system.

To avoid generating this first-chance exception, you can manually guarantee that the property sheet has the correct Window Styles. You need to set the following styles for a property sheet:

  • DS_3DLOOK

  • DS_CONTROL

  • WS_CHILD

  • WS_TABSTOP

You can use the following optional styles without causing a first-chance exception:

  • DS_SHELLFONT

  • DS_LOCALEDIT

  • WS_CLIPCHILDREN

Disable all other Windows styles because they are not compatible with property sheets. This advice does not apply to extended styles. Setting these standard styles appropriately will guarantee that the property sheet does not have to be modified and will avoid generating the first-chance exception.

Example

See the example for CPropertySheet::AddPage.

Requirements

Header: afxdlgs.h

See Also

Reference

CPropertySheet Class

Hierarchy Chart

CDialog::DoModal

CPropertySheet::Create

Other Resources

CPropertySheet Members