Share via

Property Pages (MFC)

  • Article

 

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 Property Pages (MFC).

Property pages display the current values of specific OLE control properties in a customizable, graphical interface for viewing and editing by supporting a data-mapping mechanism based on dialog data exchange (DDX).

This data-mapping mechanism maps property page controls to the individual properties of the OLE control. The value of the control property reflects the status or content of the property page control. The mapping between property page controls and properties is specified by DDP_ function calls in the property page's DoDataExchange member function. The following is a list of DDP_ functions that exchange data entered using the property page of your control:

Property Page Data Transfer

DDP_CBIndex Links the selected string's index in a combo box with a control's property.
DDP_CBString Links the selected string in a combo box with a control's property. The selected string can begin with the same letters as the property's value but does not need to match it fully.
DDP_CBStringExact Links the selected string in a combo box with a control's property. The selected string and the property's string value must match exactly.
DDP_Check Links a check box in the control's property page with a control's property.
DDP_LBIndex Links the selected string's index in a list box with a control's property.
DDP_LBString Links the selected string in a list box with a control's property. The selected string can begin with the same letters as the property's value but need not match it fully.
DDP_LBStringExact Links the selected string in a list box with a control's property. The selected string and the property's string value must match exactly.
DDP_PostProcessing Finishes the transfer of property values from your control.
DDP_Radio Links a radio button group in the control's property page with a control's property.
DDP_Text Links a control in the control's property page with a control's property. This function handles several different types of properties, such as double, short, BSTR, and long.

For more information about the DoDataExchange function and property pages, see the article ActiveX Controls: Property Pages.

The following is a list of macros used to create and manage property pages for an OLE control:

Property Pages

BEGIN_PROPPAGEIDS Begins the list of property page IDs.
END_PROPPAGEIDS Ends the list of property page IDs.
PROPPAGEID Declares a property page of the control class.

DDP_CBIndex

Call this function in your property page's DoDataExchange function to synchronize the value of an integer property with the index of the current selection in a combo box on the property page.

void AFXAPI DDP_CBIndex(
    CDataExchange* pDX,  
    int id,  
    int& member,  
    LPCTSTR pszPropName);

Parameters

pDX
Pointer to a CDataExchange object. The framework supplies this object to establish the context of the data exchange, including its direction.

id
The resource ID of the combo box control associated with the control property specified by pszPropName.

member
The member variable associated with the property page control specified by id and the property specified by pszPropName.

pszPropName
The property name of the control property to be exchanged with the combo box control specified by id.

Remarks

This function should be called before the corresponding DDX_CBIndex function call.

DDP_CBString

Call this function in your property page's DoDataExchange function to synchronize the value of a string property with the current selection in a combo box on the property page.

void AFXAPI DDP_CBString(
    CDataExchange* pDX,  
    int id,  
    CString& member,  
    LPCTSTR pszPropName);

Parameters

pDX
Pointer to a CDataExchange object. The framework supplies this object to establish the context of the data exchange, including its direction.

id
The resource ID of the combo box control associated with the control property specified by pszPropName.

member
The member variable associated with the property page control specified by id and the property specified by pszPropName.

pszPropName
The property name of the control property to be exchanged with the combo box string specified by id.

Remarks

This function should be called before the corresponding DDX_CBString function call.

DDP_CBStringExact

Call this function in your property page's DoDataExchange function to synchronize the value of a string property that exactly matches the current selection in a combo box on the property page.

void AFXAPI DDP_CBStringExact(
    CDataExchange* pDX,  
    int id,  
    CString& member,  
    LPCTSTR pszPropName);

Parameters

pDX
Pointer to a CDataExchange object. The framework supplies this object to establish the context of the data exchange, including its direction.

id
The resource ID of the combo box control associated with the control property specified by pszPropName.

member
The member variable associated with the property page control specified by id and the property specified by pszPropName.

pszPropName
The property name of the control property to be exchanged with the combo box string specified by id.

Remarks

This function should be called before the corresponding DDX_CBStringExact function call.

DDP_Check

Call this function in your property page's DoDataExchange function to synchronize the value of the property with the associated property page check box control.

void AFXAPI DDP_Check(
    CDataExchange* pDX,  
    int id,  
    int & member,  
    LPCSTR pszPropName);

Parameters

pDX
Pointer to a CDataExchange object. The framework supplies this object to establish the context of the data exchange, including its direction.

id
The resource ID of the check box control associated with the control property specified by pszPropName.

member
The member variable associated with the property page control specified by id and the property specified by pszPropName.

pszPropName
The property name of the control property to be exchanged with the check box control specified by id.

Remarks

This function should be called before the corresponding DDX_Check function call.

DDP_LBIndex

Call this function in your property page's DoDataExchange function to synchronize the value of an integer property with the index of the current selection in a list box on the property page.

void AFXAPI DDP_LBIndex(
    CDataExchange* pDX,  
    int id,  
    int& member,  
    LPCTSTR pszPropName);

Parameters

pDX
Pointer to a CDataExchange object. The framework supplies this object to establish the context of the data exchange, including its direction.

id
The resource ID of the list box control associated with the control property specified by pszPropName.

member
The member variable associated with the property page control specified by id and the property specified by pszPropName.

pszPropName
The property name of the control property to be exchanged with the list box string specified by id.

Remarks

This function should be called before the corresponding DDX_LBIndex function call.

DDP_LBString

Call this function in your property page's DoDataExchange function to synchronize the value of a string property with the current selection in a list box on the property page.

void AFXAPI DDP_LBString(
    CDataExchange* pDX,  
    int id,  
    CString& member,  
    LPCTSTR pszPropName);

Parameters

pDX
Pointer to a CDataExchange object. The framework supplies this object to establish the context of the data exchange, including its direction.

id
The resource ID of the list box control associated with the control property specified by pszPropName.

member
The member variable associated with the property page control specified by id and the property specified by pszPropName.

pszPropName
The property name of the control property to be exchanged with the list box string specified by id.

Remarks

This function should be called before the corresponding DDX_LBString function call.

DDP_LBStringExact

Call this function in your property page's DoDataExchange function to synchronize the value of a string property that exactly matches the current selection in a list box on the property page.

void AFXAPI DDP_LBStringExact(
    CDataExchange* pDX,  
    int id,  
    CString& member,  
    LPCTSTR pszPropName);

Parameters

pDX
Pointer to a CDataExchange object. The framework supplies this object to establish the context of the data exchange, including its direction.

id
The resource ID of the list box control associated with the control property specified by pszPropName.

member
The member variable associated with the property page control specified by id and the property specified by pszPropName.

pszPropName
The property name of the control property to be exchanged with the list box string specified by id.

Remarks

This function should be called before the corresponding DDX_LBStringExact function call.

DDP_PostProcessing

Call this function in your property page's DoDataExchange function, to finish the transfer of property values from the property page to your control when property values are being saved.

void AFXAPI DDP_PostProcessing(CDataExchange * pDX);

Parameters

pDX
Pointer to a CDataExchange object. The framework supplies this object to establish the context of the data exchange, including its direction.

Remarks

This function should be called after all data exchange functions are completed. For example:

void CMyAxPropPage::DoDataExchange(CDataExchange* pDX)
{
   DDP_Text(pDX, IDC_POSITIONEDIT, m_NeedlePosition, _T("NeedlePosition"));
   DDX_Text(pDX, IDC_POSITIONEDIT, m_NeedlePosition);
   DDV_MinMaxInt(pDX, m_NeedlePosition, 0, 3);
   DDP_PostProcessing(pDX);
}

DDP_Radio

Call this function in your control's DoPropExchange function to synchronize the value of the property with the associated property page radio button control.

void AFXAPI DDP_Radio(
    CDataExchange* pDX,  
    int id,  
    int & member,  
    LPCTSTR pszPropName);

Parameters

pDX
Pointer to a CDataExchange object. The framework supplies this object to establish the context of the data exchange, including its direction.

id
The resource ID of the radio button control associated with the control property specified by pszPropName.

member
The member variable associated with the property page control specified by id and the property specified by pszPropName.

pszPropName
The property name of the control property to be exchanged with the radio button control specified by id.

Remarks

This function should be called before the corresponding DDX_Radio function call.

DDP_Text

Call this function in your control's DoDataExchange function to synchronize the value of the property with the associated property page control.

void AFXAPI DDP_Text(
    CDataExchange* pDX,  
    int id,  
    BYTE & member,  
    LPCTSTR pszPropName);

void AFXAPI DDP_Text(
    CDataExchange* pDX,  
    int id,  
    int & member,  
    LPCTSTR pszPropName);

void AFXAPI DDP_Text(
    CDataExchange* pDX,  
    int id,  
    UINT & member,  
    LPCTSTR pszPropName);

void AFXAPI DDP_Text(
    CDataExchange* pDX,  
    int id,  
    long & member,  
    LPCTSTR pszPropName);

void AFXAPI DDP_Text(
    CDataExchange* pDX,  
    int id,  
    DWORD & member,  
    LPCTSTR pszPropName);

void AFXAPI DDP_Text(
    CDataExchange* pDX,  
    int id,  
    float & member,  
    LPCTSTR pszPropName);

void AFXAPI DDP_Text(
    CDataExchange* pDX,  
    int id,  
    double & member,  
    LPCTSTR pszPropName);

void AFXAPI DDP_Text(
    CDataExchange* pDX,  
    int id,  
    CString & member,  
    LPCTSTR pszPropName);

Parameters

pDX
Pointer to a CDataExchange object. The framework supplies this object to establish the context of the data exchange, including its direction.

id
The resource ID of the control associated with the control property specified by pszPropName.

member
The member variable associated with the property page control specified by id and the property specified by pszPropName.

pszPropName
The property name of the control property to be exchanged with the control specified by id.

Remarks

This function should be called before the corresponding DDX_Text function call.

BEGIN_PROPPAGEIDS

Begins the definition of your control's list of property page IDs.

BEGIN_PROPPAGEIDS
(class_name,  count)

Parameters

class_name
The name of the control class for which property pages are being specified.

count
The number of property pages used by the control class.

Remarks

In the implementation (.cpp) file that defines the member functions for your class, start the property page list with the BEGIN_PROPPAGEIDS macro, then add macro entries for each of your property pages, and complete the property page list with the END_PROPPAGEIDS macro.

For more information on property pages, see the article ActiveX Controls: Property Pages.

END_PROPPAGEIDS

Ends the definition of your property page ID list.

END_PROPPAGEIDS
(class_name)

Parameters

class_name
The name of the control class that owns the property page.

PROPPAGEID

Adds a property page for use by your OLE control.

PROPPAGEID
(clsid)

Parameters

clsid
The unique class ID of a property page.

Remarks

All PROPPAGEID macros must be placed between the BEGIN_PROPPAGEIDS and END_PROPPAGEIDS macros in your control's implementation file.

See Also

Macros and Globals