CSnapInPropertyPageImpl Class

 

For the latest documentation on Visual Studio 2017, see Visual Studio 2017 Documentation.

For the latest documentation on Visual Studio 2017, see CSnapInPropertyPageImpl Class on docs.microsoft.com. This class provides methods for implementing a snap-in property page object.

System_CAPS_ICON_important.jpg Important

This class and its members cannot be used in applications that execute in the Windows Runtime.

CSnapInPropertyPageImpl : public CDialogImplBase

Public Constructors

NameDescription
CSnapInPropertyPageImpl::CSnapInPropertyPageImplConstructor.

Public Methods

NameDescription
CSnapInPropertyPageImpl::CancelToCloseChanges the status of the OK and Cancel buttons.
CSnapInPropertyPageImpl::CreateInitializes a newly created CSnapInPropertyPageImpl object.
CSnapInPropertyPageImpl::OnApplyCalled by the framework when the user clicks the Apply Now button while using a wizard-type property sheet.
CSnapInPropertyPageImpl::OnHelpCalled by the framework when the user clicks the Help button while using a wizard-type property sheet.
CSnapInPropertyPageImpl::OnKillActiveCalled by the framework when the current page is no longer active.
CSnapInPropertyPageImpl::OnQueryCancelCalled by the framework when the user clicks the Cancel button and before the cancel has taken place.
CSnapInPropertyPageImpl::OnResetCalled by the framework when the user clicks the Reset button while using a wizard-type property sheet.
CSnapInPropertyPageImpl::OnSetActiveCalled by the framework when the current page becomes active.
CSnapInPropertyPageImpl::OnWizardBackCalled by the framework when the user clicks the Back button while using a wizard-type property sheet.
CSnapInPropertyPageImpl::OnWizardFinishCalled by the framework when the user clicks the Finish button while using a wizard-type property sheet.
CSnapInPropertyPageImpl::OnWizardNextCalled by the framework when the user clicks the Next button while using a wizard-type property sheet.
CSnapInPropertyPageImpl::QuerySiblingsForwards the current message to all pages of the property sheet.
CSnapInPropertyPageImpl::SetModifiedCall to activate or deactivate the Apply Now button.

Public Data Members

NameDescription
CSnapInPropertyPageImpl::m_pspThe Windows PROPSHEETPAGE structure used by the CSnapInPropertyPageImpl object.

CSnapInPropertyPageImpl provides a basic implementation for a snap-in property page object. The basic features of a snap-in property page are implemented using several different interfaces and map types.

CDialogImplBase

CSnapInPropertyPageImpl

Header: atlsnap.h

Call this function after an unrecoverable change has been made to the data in a page of a modal property sheet.

void CancelToClose();

Remarks

This function will change the OK button to Close and disable the Cancel button. This change alerts the user that a change is permanent and the modifications cannot be cancelled.

The CancelToClose member function does nothing in a modeless property sheet, because a modeless property sheet does not have a Cancel button by default.

Constructs a CSnapInPropertyPageImpl object.

CSnapInPropertyPageImpl(LPCTSTR lpszTitle = NULL);

Parameters

lpszTitle
[in] The title of the property page.

Remarks

To initialize the underlying structure, call CSnapInPropertyPageImpl::Create.

Call this function to initialize the underlying structure of the property page.

HPROPSHEETPAGE Create();

Return Value

A handle to a PROPSHEETPAGE structure containing the attributes of the newly created property sheet.

Remarks

You should first call CSnapInPropertyPageImpl::CSnapInPropertyPageImpl before calling this function.

m_psp is a structure whose members store the characteristics of PROPSHEETPAGE.

PROPSHEETPAGE m_psp;

Remarks

Use this structure to initialize the appearance of a property page after it is constructed.

For more information on this structure, including a listing of its members, see PROPSHEETPAGE in the Windows SDK.

This member function is called when the user clicks the OK or the Apply Now button.

BOOL OnApply();

Return Value

Nonzero if the changes are accepted; otherwise 0.

Remarks

Before OnApply can be called by the framework, you must have called SetModified and set its parameter to TRUE. This will activate the Apply Now button as soon as the user makes a change on the property page.

Override this member function to specify what action your program takes when the user clicks the Apply Now button. When overriding, the function should return TRUE to accept changes and FALSE to prevent changes from taking effect.

The default implementation of OnApply returns TRUE.

This member function is called when the user clicks the Help button for the property page.

void OnHelp();

Remarks

Override this member function to display help for the property page.

This member function is called when the page is no longer the active page.

BOOL OnKillActive();

Return Value

Nonzero if data was updated successfully; otherwise 0.

Remarks

Override this member function to perform special data validation tasks.

This member function is called when the user clicks the Cancel button and before the cancel action has taken place.

BOOL OnQueryCancel();

Return Value

Nonzero to allow the cancel operation; otherwise 0.

Remarks

Override this member function to specify an action the program takes when the user clicks the Cancel button.

The default implementation of OnQueryCancel returns TRUE.

This member function is called when the user clicks the Cancel button.

void OnReset();

Remarks

When this function is called, changes to all property pages that were made by the user previously clicking the Apply Now button are discarded, and the property sheet retains focus.

Override this member function to specify what action the program takes when the user clicks the Cancel button.

This member function is called when the page is chosen by the user and becomes the active page.

BOOL OnSetActive();

Return Value

Nonzero if the page was successfully set active; otherwise 0.

Remarks

Override this member function to perform tasks when a page is activated. Your override of this member function should call the default version before any other processing is done.

The default implementation returns TRUE.

This member function is called when the user clicks the Back button in a wizard.

BOOL OnWizardBack();

Return Value

  • 0 to automatically advance to the previous page.

  • –1 to prevent the page from changing.

To jump to a page other than the next one, return the identifier of the dialog box to be displayed.

Remarks

Override this member function to specify some action the user must take when the Back button is clicked.

This member function is called when the user clicks the Finish button in a wizard.

BOOL OnWizardFinish();

Return Value

Nonzero if the property sheet is destroyed when the wizard finishes; otherwise zero.

Remarks

Override this member function to specify some action the user must take when the Finish button is clicked.

This member function is called when the user clicks the Next button in a wizard.

BOOL OnWizardNext();

Return Value

  • 0 to automatically advance to the next page.

  • –1 to prevent the page from changing.

To jump to a page other than the next one, return the identifier of the dialog box to be displayed.

Remarks

Override this member function to specify some action the user must take when the Next button is clicked.

Call this member function to forward a message to each page in the property sheet.

LRESULT QuerySiblings(WPARAM wParam, LPARAM lParam);

Parameters

wParam
[in] Specifies additional message-dependent information.

lParam
[in] Specifies additional message-dependent information.

Return Value

Nonzero if the message should not be forwarded to the next property page; otherwise zero.

Remarks

If a page returns a nonzero value, the property sheet does not send the message to subsequent pages.

Call this member function to enable or disable the Apply Now button, based on whether the settings in the property page should be applied to the appropriate external object.

void SetModified(BOOL bChanged = TRUE);

Parameters

bChanged
[in] TRUE to indicate that the property page settings have been modified since the last time they were applied; FALSE to indicate that the property page settings have been applied, or should be ignored.

Remarks

The property sheet keeps track of which pages are "dirty," that is, property pages for which you have called SetModified( TRUE ). The Apply Now button will always be enabled if you call SetModified( TRUE ) for one of the pages. The Apply Now button will be disabled when you call SetModified( FALSE ) for one of the pages, but only if none of the other pages is "dirty."

Class Overview

Show: