Share via


CSnapInPropertyPageImpl Class

 

The new home for Visual Studio documentation is Visual Studio 2017 Documentation on docs.microsoft.com.

The latest version of this topic can be found at CSnapInPropertyPageImpl Class.

This class provides methods for implementing a snap-in property page object.

Important

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

Syntax

CSnapInPropertyPageImpl : public CDialogImplBase

Members

Public Constructors

Name Description
CSnapInPropertyPageImpl::CSnapInPropertyPageImpl Constructor.

Public Methods

Name Description
CSnapInPropertyPageImpl::CancelToClose Changes the status of the OK and Cancel buttons.
CSnapInPropertyPageImpl::Create Initializes a newly created CSnapInPropertyPageImpl object.
CSnapInPropertyPageImpl::OnApply Called by the framework when the user clicks the Apply Now button while using a wizard-type property sheet.
CSnapInPropertyPageImpl::OnHelp Called by the framework when the user clicks the Help button while using a wizard-type property sheet.
CSnapInPropertyPageImpl::OnKillActive Called by the framework when the current page is no longer active.
CSnapInPropertyPageImpl::OnQueryCancel Called by the framework when the user clicks the Cancel button and before the cancel has taken place.
CSnapInPropertyPageImpl::OnReset Called by the framework when the user clicks the Reset button while using a wizard-type property sheet.
CSnapInPropertyPageImpl::OnSetActive Called by the framework when the current page becomes active.
CSnapInPropertyPageImpl::OnWizardBack Called by the framework when the user clicks the Back button while using a wizard-type property sheet.
CSnapInPropertyPageImpl::OnWizardFinish Called by the framework when the user clicks the Finish button while using a wizard-type property sheet.
CSnapInPropertyPageImpl::OnWizardNext Called by the framework when the user clicks the Next button while using a wizard-type property sheet.
CSnapInPropertyPageImpl::QuerySiblings Forwards the current message to all pages of the property sheet.
CSnapInPropertyPageImpl::SetModified Call to activate or deactivate the Apply Now button.

Public Data Members

Name Description
CSnapInPropertyPageImpl::m_psp The Windows PROPSHEETPAGE structure used by the CSnapInPropertyPageImpl object.

Remarks

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.

Inheritance Hierarchy

CDialogImplBase

CSnapInPropertyPageImpl

Requirements

Header: atlsnap.h

CSnapInPropertyPageImpl::CancelToClose

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.

CSnapInPropertyPageImpl::CSnapInPropertyPageImpl

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.

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.

CSnapInPropertyPageImpl::m_psp

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.

CSnapInPropertyPageImpl::OnApply

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.

CSnapInPropertyPageImpl::OnHelp

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.

CSnapInPropertyPageImpl::OnKillActive

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.

CSnapInPropertyPageImpl::OnQueryCancel

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.

CSnapInPropertyPageImpl::OnReset

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.

CSnapInPropertyPageImpl::OnSetActive

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.

CSnapInPropertyPageImpl::OnWizardBack

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.

CSnapInPropertyPageImpl::OnWizardFinish

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.

CSnapInPropertyPageImpl::OnWizardNext

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.

CSnapInPropertyPageImpl::QuerySiblings

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.

CSnapInPropertyPageImpl::SetModified

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."

See Also

Class Overview