Property Map Macros
The latest version of this topic can be found at Property Map Macros.
These macros define property maps and entries.
| 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. |
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.