The ICategorizeProperties and IAcPiCategorizeProperties interfaces are used to categorize properties shown in the Property Inspector control. IAcPiCategorizeProperties is an updated version of the legacy ICategorizeProperties interface. An object may implement one or the other, but not both. The IAcPiCategorizeProperties interface duplicates its predecessor's functionality and adds the following features:
Use of a categorizing interface is optional, but strongly recommended. If an object does not implement one of these interfaces, all of its properties are categorized under General.
The Property Inspector asks an object's QueryInterface() method for an ICategorizeProperties or an IAcPiCategorizeProperties pointer when it is collecting property information. If the QueryInterface() call succeeds, the Property Inspector uses the obtained pointer to call the MapPropertyToCategory() method for each property defined by the object's type information. If a returned category is not one of the values predefined in the inc\category.h file, the GetCategoryName() method is called to get the display name for the custom category.
If you plan to use only predefined categories, you can return E_NOTIMPL or S_FALSE from GetCategoryName(). You also do not need to implement the MapPropertyToCategory() method. Instead, the Property Inspector uses the category indicated for each property in your OPM property map. This technique is used in the AsdkSquareWrapper_DG sample project. If a property is not found in the property map, the Property Inspector displays it under the General category.
To categorize properties, you must know the DISPID for each property. The Active Template Library (ATL) assigns property DISPID values in the IDL file that defines your interface. These numbers are found in the id() declaration of the property attribute list, as shown below:
[propget, id(1), helpstring("property Number")] HRESULT Number([out, retval] short *pVal);
In this example, the DISPID for the Number property is 1.