Edit

Property Map Macros

  • Article

These macros define property maps and entries.

Name Description
BEGIN_PROP_MAP Marks the beginning of the ATL property map.
PROP_DATA_ENTRY Indicates the extent, or dimensions, of an ActiveX control.
PROP_ENTRY_TYPE Enters a property description, property DISPID, and property page CLSID into the property map.
PROP_ENTRY_TYPE_EX Enters a property description, property DISPID, property page CLSID, and IDispatch IID into the property map.
PROP_PAGE Enters a property page CLSID into the property map.
END_PROP_MAP Marks the end of the ATL property map.

Requirements

Header: atlcom.h

BEGIN_PROP_MAP

Marks the beginning of the object's property map.

BEGIN_PROP_MAP(theClass)

Parameters

theClass
[in] Specifies the class containing the property map.

Remarks

The property map stores property descriptions, property DISPIDs, property page CLSIDs, and IDispatch IIDs. Classes IPerPropertyBrowsingImpl, IPersistPropertyBagImpl, IPersistStreamInitImpl, and ISpecifyPropertyPagesImpl use the property map to retrieve and set this information.

When you create an object with the ATL Project Wizard, the wizard will create an empty property map by specifying BEGIN_PROP_MAP followed by END_PROP_MAP.

BEGIN_PROP_MAP does not save out the extent (that is, the dimensions) of a property map, because an object using a property map may not have a user interface, so it would have no extent. If the object is an ActiveX control with a user interface, it has an extent. In this case, you must specify PROP_DATA_ENTRY in your property map to supply the extent.

Example

BEGIN_PROP_MAP(CMyPropCtrl)
   PROP_DATA_ENTRY("_cx", m_sizeExtent.cx, VT_UI4)
   PROP_DATA_ENTRY("_cy", m_sizeExtent.cy, VT_UI4)
   PROP_ENTRY_TYPE("Property1", 1, CLSID_MyPropPage1, VT_BSTR)
   PROP_ENTRY_TYPE_EX("Caption", DISPID_CAPTION, CLSID_MyPropPage2, IID_IMyDual1, VT_BSTR)
   PROP_ENTRY_INTERFACE_CALLBACK("CorrectParamCallback", 0, CLSID_MyPropPage1, AllowedCLSID, VT_DISPATCH)
   PROP_ENTRY_INTERFACE_CALLBACK_EX("CorrectParamCallbackEx", 1, IID_IMyDual1, CLSID_MyPropPage2, AllowedCLSID, VT_UNKNOWN)
   PROP_PAGE(CLSID_MyPropPage3)
END_PROP_MAP()

PROP_DATA_ENTRY

Indicates the extent, or dimensions, of an ActiveX control.

PROP_DATA_ENTRY( szDesc, member, vt)

Parameters

szDesc
[in] The property description.

member
[in] The data member containing the extent; for example, m_sizeExtent.

vt
[in] Specifies the VARIANT type of the property.

Remarks

This macro causes the specified data member to be persisted.

When you create an ActiveX control, the wizard inserts this macro after the property map macro BEGIN_PROP_MAP and before the property map macro END_PROP_MAP.

Example

In the following example, the extent of the object (m_sizeExtent) is being persisted.

BEGIN_PROP_MAP(CMyWindow)
   PROP_DATA_ENTRY("_cx", m_sizeExtent.cx, VT_UI4)
   PROP_DATA_ENTRY("_cy", m_sizeExtent.cy, VT_UI4)
END_PROP_MAP()

 

BEGIN_PROP_MAP(CMyCompositeCtrl)
   PROP_DATA_ENTRY("Width", m_nWidth, VT_UI4)
   PROP_DATA_ENTRY("Height", m_nHeight, VT_UI4)
END_PROP_MAP()

PROP_ENTRY_TYPE

Use this macro to enter a property description, property DISPID, and property page CLSID into the object's property map.

PROP_ENTRY_TYPE( szDesc, dispid, clsid, vt)

Parameters

szDesc
[in] The property description.

dispid
[in] The property's DISPID.

clsid
[in] The CLSID of the associated property page. Use the special value CLSID_NULL for a property that does not have an associated property page.

vt
[in] The property's type.

Remarks

The PROP_ENTRY macro was insecure and deprecated. It has been replaced with PROP_ENTRY_TYPE.

The BEGIN_PROP_MAP macro marks the beginning of the property map; the END_PROP_MAP macro marks the end.

Example

See the example for BEGIN_PROP_MAP.

PROP_ENTRY_TYPE_EX

Similar to PROP_ENTRY_TYPE, but allows you specify a particular IID if your object supports multiple dual interfaces.

PROP_ENTRY_TYPE_EX( szDesc, dispid, clsid, iidDispatch, vt)

Parameters

szDesc
[in] The property description.

dispid
[in] The property's DISPID.

clsid
[in] The CLSID of the associated property page. Use the special value CLSID_NULL for a property that does not have an associated property page.

iidDispatch
[in] The IID of the dual interface defining the property.

vt
[in] The property's type.

Remarks

The PROP_ENTRY_EX macro was insecure and deprecated. It has been replaced with PROP_ENTRY_TYPE_EX.

The BEGIN_PROP_MAP macro marks the beginning of the property map; the END_PROP_MAP macro marks the end.

Example

The following example groups entries for IMyDual1 followed by an entry for IMyDual2. Grouping by dual interface will improve performance.

BEGIN_PROP_MAP(CAtlEdit)
   PROP_ENTRY_TYPE_EX("Caption", DISPID_CAPTION, CLSID_MyPropPage2, IID_IMyDual1, VT_BSTR)
   PROP_ENTRY_TYPE_EX("Enabled", DISPID_ENABLED, CLSID_MyPropPage2, IID_IMyDual1, VT_BOOL)
   PROP_ENTRY_TYPE_EX("Width", DISPID_DRAWWIDTH, CLSID_MyPropPage2, IID_IMyDual2, VT_UINT)
END_PROP_MAP()

PROP_PAGE

Use this macro to enter a property page CLSID into the object's property map.

PROP_PAGE(clsid)

Parameters

clsid
[in] The CLSID of a property page.

Remarks

PROP_PAGE is similar to PROP_ENTRY_TYPE, but does not require a property description or DISPID.

Note

If you have already entered a CLSID with PROP_ENTRY_TYPE or PROP_ENTRY_TYPE_EX, you do not need to make an additional entry with PROP_PAGE.

The BEGIN_PROP_MAP macro marks the beginning of the property map; the END_PROP_MAP macro marks the end.

Example

BEGIN_PROP_MAP(CMyCtrl)
   OtherPropMapEntries
   PROP_PAGE(CLSID_DatePage)
   PROP_PAGE(CLSID_StockColorPage)
END_PROP_MAP()

END_PROP_MAP

Marks the end of the object's property map.

END_PROP_MAP()

Remarks

When you create an object with the ATL Project Wizard, the wizard will create an empty property map by specifying BEGIN_PROP_MAP followed by END_PROP_MAP.

Example

See the example for BEGIN_PROP_MAP.

See also

Macros