| description | title | ms.date | f1_keywords | helpviewer_keywords | ||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Learn more about: CPropertyPage Class |
CPropertyPage Class |
11/04/2016 |
|
|
Represents individual pages of a property sheet, otherwise known as a tab dialog box.
class CPropertyPage : public CDialog
| Name | Description |
|---|---|
CPropertyPage::CPropertyPage |
Constructs a CPropertyPage object. |
| Name | Description |
|---|---|
CPropertyPage::CancelToClose |
Changes the OK button to read Close, and disables the Cancel button, after an unrecoverable change in the page of a modal property sheet. |
CPropertyPage::Construct |
Constructs a CPropertyPage object. Use Construct if you want to specify your parameters at run time, or if you're using arrays. |
CPropertyPage::GetPSP |
Retrieves the Windows PROPSHEETPAGE structure associated with the CPropertyPage object. |
CPropertyPage::OnApply |
Called by the framework when the Apply Now button is clicked. |
CPropertyPage::OnCancel |
Called by the framework when the Cancel button is clicked. |
CPropertyPage::OnKillActive |
Called by the framework when the current page is no longer the active page. Perform data validation here. |
CPropertyPage::OnOK |
Called by the framework when the OK, Apply Now, or Close button is clicked. |
CPropertyPage::OnQueryCancel |
Called by the framework when the Cancel button is clicked, and before the cancel has taken place. |
CPropertyPage::OnReset |
Called by the framework when the Cancel button is clicked. |
CPropertyPage::OnSetActive |
Called by the framework when the page is made the active page. |
CPropertyPage::OnWizardBack |
Called by the framework when the Back button is clicked while using a wizard-type property sheet. |
CPropertyPage::OnWizardFinish |
Called by the framework when the Finish button is clicked while using a wizard-type property sheet. |
CPropertyPage::OnWizardNext |
Called by the framework when the Next button is clicked while using a wizard-type property sheet. |
CPropertyPage::QuerySiblings |
Forwards the message to each page of the property sheet. |
CPropertyPage::SetModified |
Call to activate or deactivate the Apply Now button. |
| Name | Description |
|---|---|
CPropertyPage::m_psp |
The Windows PROPSHEETPAGE structure. Provides access to basic property page parameters. |
As with standard dialog boxes, you derive a class from CPropertyPage for each page in your property sheet. To use CPropertyPage-derived objects, first create a CPropertySheet object, and then create an object for each page that goes in the property sheet. Call CPropertySheet::AddPage for each page in the sheet, and then display the property sheet by calling CPropertySheet::DoModal for a modal property sheet, or CPropertySheet::Create for a modeless property sheet.
You can create a type of tab dialog box called a wizard, which consists of a property sheet with a sequence of property pages that guide the user through the steps of an operation, such as setting up a device or creating a newsletter. In a wizard-type tab dialog box, the property pages don't have tabs, and only one property page is visible at a time. Also, instead of having OK and Apply Now buttons, a wizard-type tab dialog box has a Back button, a Next or Finish button, and a Cancel button.
For more information on establishing a property sheet as a wizard, see CPropertySheet::SetWizardMode. For more information on using CPropertyPage objects, see the article Property Sheets and Property Pages.
CPropertyPage
Header: afxdlgs.h
Call this function after an unrecoverable change has been made to the data in a page of a modal property sheet.
void CancelToClose();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 can't be canceled.
The CancelToClose member function does nothing in a modeless property sheet, because a modeless property sheet doesn't have a Cancel button by default.
See the example for CPropertyPage::QuerySiblings.
Call this member function to construct a CPropertyPage object.
void Construct(
UINT nIDTemplate,
UINT nIDCaption = 0);
void Construct(
LPCTSTR lpszTemplateName,
UINT nIDCaption = 0);
void Construct(
UINT nIDTemplate,
UINT nIDCaption,
UINT nIDHeaderTitle,
UINT nIDHeaderSubTitle = 0);
void Construct(
LPCTSTR lpszTemplateName,
UINT nIDCaption,
UINT nIDHeaderTitle,
UINT nIDHeaderSubTitle = 0);nIDTemplate
ID of the template used for this page.
nIDCaption
ID of the name to be placed in the tab for this page. If 0, the name will be taken from the dialog template for this page.
lpszTemplateName
Contains a null-terminated string that is the name of a template resource.
nIDHeaderTitle
ID of the name to be placed in the title location of the property page header. By default, 0.
nIDHeaderSubTitle
ID of the name to be placed in the subtitle location of the property page header. By default, 0.
The object is displayed after all of the following conditions are met:
-
The page has been added to a property sheet using
CPropertySheet::AddPage. -
The property sheet's
DoModalorCreatefunction has been called. -
The user has selected (tabbed to) this page.
Call Construct if one of the other class constructors hasn't been called. The Construct member function is flexible because you can leave the parameter statement blank and then specify multiple parameters and construction at any point in your code.
You must use Construct when you work with arrays, and you must call Construct for each member of the array so that the data members are assigned proper values.
[!code-cppNVC_MFCDocView#112]
Constructs a CPropertyPage object.
CPropertyPage();
explicit CPropertyPage(
UINT nIDTemplate,
UINT nIDCaption = 0,
DWORD dwSize = sizeof(PROPSHEETPAGE));
explicit CPropertyPage(
LPCTSTR lpszTemplateName,
UINT nIDCaption = 0,
DWORD dwSize = sizeof(PROPSHEETPAGE));
CPropertyPage(
UINT nIDTemplate,
UINT nIDCaption,
UINT nIDHeaderTitle,
UINT nIDHeaderSubTitle = 0,
DWORD dwSize = sizeof(PROPSHEETPAGE));
CPropertyPage(
LPCTSTR lpszTemplateName,
UINT nIDCaption,
UINT nIDHeaderTitle,
UINT nIDHeaderSubTitle = 0,
DWORD dwSize = sizeof(PROPSHEETPAGE));
nIDTemplate
ID of the template used for this page.
nIDCaption
ID of the name to be placed in the tab for this page. If 0, the name will be taken from the dialog template for this page.
dwSize
lpszTemplateName
Points to a string containing the name of the template for this page. Can't be NULL.
nIDHeaderTitle
ID of the name to be placed in the title location of the property page header.
nIDHeaderSubTitle
ID of the name to be placed in the subtitle location of the property page header.
The object is displayed after all of the following conditions are met:
-
The page has been added to a property sheet using
CPropertySheet::AddPage. -
The property sheet's
DoModalorCreatefunction has been called. -
The user has selected (tabbed to) this page.
If you have multiple parameters (for example, if you're using an array), use CPropertySheet::Construct instead of CPropertyPage.
[!code-cppNVC_MFCDocView#113]
Retrieves the Windows PROPSHEETPAGE structure associated with the CPropertyPage object.
const PROPSHEETPAGE& GetPSP() const;
PROPSHEETPAGE& GetPSP();
A reference to the PROPSHEETPAGE structure.
m_psp is a structure whose members store the characteristics of PROPSHEETPAGE.
PROPSHEETPAGE m_psp;
Use this structure to initialize the appearance of a property page after it's constructed.
For more information on this structure, including a listing of its members, see PROPSHEETPAGE in the Windows SDK.
[!code-cppNVC_MFCDocView#128]
This member function is called by the framework when the user chooses the OK or the Apply Now button.
virtual BOOL OnApply();
Nonzero if the changes are accepted; otherwise 0.
When the framework calls this function, changes made on all property pages in the property sheet are accepted, the property sheet retains focus, and OnApply returns TRUE (the value 1). 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 selects 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 calls OnOK.
For more information about notification messages sent when the user presses the Apply Now or OK button in a property sheet, see PSN_APPLY in the Windows SDK.
See the example for CPropertyPage::OnOK.
This member function is called by the framework when the Cancel button is selected.
virtual void OnCancel();
Override this member function to perform Cancel button actions. The default negates any changes that have been made.
[!code-cppNVC_MFCDocView#114]
This member function is called by the framework when the page is no longer the active page.
virtual BOOL OnKillActive();
Nonzero if data was updated successfully, otherwise 0.
Override this member function to perform special data validation tasks.
The default implementation of this member function copies settings from the controls in the property page to the member variables of the property page. If the data wasn't updated successfully due to a dialog data validation (DDV) error, the page retains focus.
After this member function returns successfully, the framework will call the page's OnOK function.
[!code-cppNVC_MFCDocView#115]
This member function is called by the framework when the user chooses either the OK or the Apply Now button, immediately after the framework calls OnKillActive.
virtual void OnOK();
When the user chooses either the OK or the Apply Now button, the framework receives the PSN_APPLY notification from the property page. The call to OnOK won't be made if you call CPropertySheet::PressButton because the property page doesn't send the notification in that case.
Override this member function to implement additional behavior specific to the currently active page when user dismisses the entire property sheet.
The default implementation of this member function marks the page as "clean" to reflect that the data was updated in the OnKillActive function.
[!code-cppNVC_MFCDocView#116]
This member function is called by the framework when the user selects the Cancel button and before the cancel action has taken place.
virtual BOOL OnQueryCancel();
Returns FALSE to prevent the cancel operation or TRUE to allow it.
Override this member function to specify an action the program takes when the user selects the Cancel button.
The default implementation of OnQueryCancel returns TRUE.
[!code-cppNVC_MFCDocView#117]
This member function is called by the framework when the user chooses the Cancel button.
virtual void OnReset();
When the framework calls this function, changes to all property pages that were made by the user previously choosing 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 selects the Cancel button.
The default implementation of OnReset does nothing.
See the example for CPropertyPage::OnCancel.
This member function is called by the framework when the page is chosen by the user and becomes the active page.
virtual BOOL OnSetActive();
Nonzero if the page was successfully set active; otherwise 0.
Override this member function to perform tasks when a page is activated. Your override of this member function would typically call the default version after updating data members, to allow it to update the page controls with the new data.
The default implementation creates the window for the page, if not previously created, and makes it the active page.
See the example for CPropertySheet::SetFinishText.
This member function is called by the framework when the user selects the Back button in a wizard.
virtual LRESULT OnWizardBack();
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 to be displayed.
Override this member function to specify some action the user must take when the Back button is pressed.
For more information on how to make a wizard-type property sheet, see CPropertySheet::SetWizardMode.
[!code-cppNVC_MFCDocView#118]
This member function is called by the framework when the user selects the Finish button in a wizard.
virtual BOOL OnWizardFinish();
Nonzero if the property sheet is destroyed when the wizard finishes; otherwise zero.
When a user selects the Finish button in a wizard, the framework calls this function; when OnWizardFinish returns TRUE (a nonzero value), the property sheet is able to be destroyed (but isn't actually destroyed). Call DestroyWindow to destroy the property sheet. Don't call DestroyWindow from OnWizardFinish; doing so will cause heap corruption or other errors.
You can override this member function to specify some action the user must take when the Finish button is pressed. When overriding this function, return FALSE to prevent the property sheet from being destroyed.
For more information about notification messages sent when the user presses the Finish button in a wizard property sheet, see PSN_WIZFINISH in the Windows SDK.
For more information on how to make a wizard-type property sheet, see CPropertySheet::SetWizardMode.
[!code-cppNVC_MFCDocView#119] [!code-cppNVC_MFCDocView#120] [!code-cppNVC_MFCDocView#121] [!code-cppNVC_MFCDocView#122]
This member function is called by the framework when the user selects the Next button in a wizard.
virtual LRESULT OnWizardNext();
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 to be displayed.
Override this member function to specify some action the user must take when the Next button is pressed.
For more information on how to make a wizard-type property sheet, see CPropertySheet::SetWizardMode.
[!code-cppNVC_MFCDocView#123]
Call this member function to forward a message to each page in the property sheet.
LRESULT QuerySiblings(
WPARAM wParam,
LPARAM lParam);
wParam
Specifies additional message-dependent information.
lParam
Specifies additional message-dependent information
The nonzero value from a page in the property sheet, or 0 if all pages return a value of 0.
If a page returns a nonzero value, the property sheet doesn't send the message to subsequent pages.
[!code-cppNVC_MFCDocView#124] [!code-cppNVC_MFCDocView#125] [!code-cppNVC_MFCDocView#126]
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);bChanged
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.
The framework 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."
[!code-cppNVC_MFCDocView#127]
MFC Sample CMNCTRL1
MFC Sample CMNCTRL2
MFC Sample PROPDLG
MFC Sample SNAPVW
CDialog Class
Hierarchy Chart
CPropertySheet Class