Adding a Property to an Interface or Non-MFC Dispinterface

Overview |  How Do I ... Topics

When you use the Add Property dialog box to define a new property for an ATL, Java, or user-defined interface, ClassView defines two default attributes for you: id and helpstring. The id attribute assigns a DISPID. The helpstring is a placeholder for text that can be used in the interface, for example in a status bar or ToolTip.

To add a property to an interface or non-MFC dispinterface

1. First save the .idl file for the class.

   This enables the parser to correctly identify the location of all elements in the file.

2. In ClassView, rest your cursor on the interface or dispinterface and click the right mouse button to invoke the shortcut menu.

   Note   For ATL classes, the dispinterface (event source interface) is identified with the name I<MyObject>Events.

3. Click Add Property.
   
   
4. Select the return type and property type for the property.

   For dual interfaces and dispinterfaces, accept the default return type of HRESULT. Use the property type to pass a value by means of the parameter list rather than the return type.

   Note   HRESULT is the recommended return type, even for custom interfaces, since it provides a standard way to return error codes.

5. Enter the name and any parameters for this property.

   The Implementation area displays the options you’ve specified so far, in addition to the default id and helpstring attributes.

6. In the Function Type area, select the options you want:
   • To make the property read-only, clear the Put Function check box.
     
     
   • For objects that have large initialization overhead, you may want to select the PropPutRef option. This returns a reference to the object, while the more common PropPut option returns a copy of the object itself.

   Any attributes you define for this property (see step 7) will be applied to the Get and Put functions specified here.

7. Click the Attributes button to specify additional attributes for this property or to modify the default attributes.
   
   
8. For every attribute you wish to define:
   • Select the attribute from the Name list box.
     
     
   • Specify its value (if any) by typing it into the Value text box.

     Only four attributes take a value: id, call_as, helpstring, and helpcontext.

   For a description of the attributes available from the list, see the Attribute Definition Table.

9. Click OK to return to the Add Property dialog box.

   The Implementation area reflects the attributes you have just specified. You can continue to add, delete, or modify attributes by returning to the Edit Attributes dialog box, until you exit the Add Property dialog box.

10. When you are satisfied with the method definition, click OK to exit the Add Property dialog box.

The property in its Get and Put variants is now visible as an icon in ClassView, under the interface where it is defined. You can double-click the icon to view the new property declaration in the .idl or .odl file.

For ATL interfaces, stub Get and Put functions are added to the .cpp file, and references to these functions are added to the .h file.

For ATL dispinterfaces (event source interfaces), the stub functions are added to the <ObjectName>cp.h file that gets created when you implement a connection point for the object. (You must first compile the .idl file.) For more information, see Adding Connection Points to an Object.