|
| 1 | +--- |
| 2 | +description: "Learn more about: Use a Microsoft Visual Studio wizard to add an IDL property to an IDL interface in your project" |
| 3 | +title: "Add an IDL property" |
| 4 | +ms.date: 04/11/2022 |
| 5 | +f1_keywords: ["vc.codewiz.prop.overview", "vc.codewiz.prop.idlattributes"] |
| 6 | +helpviewer_keywords: ["interfaces, adding properties", "properties [C++], adding to interfaces", "names, add property wizard", "IDL attributes", "stock properties, about stock properties", "stock properties"] |
| 7 | +ms.custom: devdivchpfy22 |
| 8 | +--- |
| 9 | +# Add an IDL property |
| 10 | + |
| 11 | +The **Add IDL Property** wizard adds a method to an interface defined in an Interface Definition Library (IDL). To use the **Add IDL Property** wizard, your project can't support MFC. |
| 12 | + |
| 13 | +For example, if you have an ATL project, and it has an `.idl` file in it, use the following procedure to add a property to an interface. |
| 14 | + |
| 15 | +This wizard differs from the **Add Property** wizard and **Add IDL MFC Property** wizard. The [Add Property](adding-a-property-visual-cpp.md) wizard adds a property to your project. The **Add IDL MFC Property** wizard is specific to MFC, ActiveX, or ATL projects that support MFC. |
| 16 | + |
| 17 | +**To add an IDL property** |
| 18 | + |
| 19 | +1. On the **View** menu, select **Class View**. |
| 20 | + |
| 21 | +1. In [Class View](/visualstudio/ide/viewing-the-structure-of-code), right-click the name of the interface to which you want to add the property. |
| 22 | + |
| 23 | + > [!NOTE] |
| 24 | + > You can also add properties to dispinterfaces, which, unless the project is attributed, are nested within the library node. |
| 25 | +
|
| 26 | +1. From the shortcut menu, select **Add** > **Add Property**. |
| 27 | + |
| 28 | +1. In the **Add IDL Property** wizard, provide the information to create the property. |
| 29 | + |
| 30 | +1. Select **OK** to add the property. |
| 31 | + |
| 32 | +The `Get` and `Put` methods of the property are displayed as two icons in **Class View**, under the interface where it's defined. You can double-click either icon to view the property declaration in the `.idl` file. |
| 33 | + |
| 34 | +For ATL interfaces, the `Get` and `Put` functions are added to the `.cpp` and `.h` files. |
| 35 | + |
| 36 | +## Add an IDL property wizard |
| 37 | + |
| 38 | +The following section describes the UI that you'll use to add an IDL property: |
| 39 | + |
| 40 | +:::image type="content" source="media/add-interface-definition-library-property-wizard.png" alt-text="Screenshot of adding IDL property to the interface."::: |
| 41 | + |
| 42 | +- **Property name** |
| 43 | + |
| 44 | + Sets the name of the property. |
| 45 | + |
| 46 | +- **Property type** |
| 47 | + |
| 48 | + Sets whether your property will have a getter, setter, or both. |
| 49 | + |
| 50 | +- **Return type** |
| 51 | + |
| 52 | + For ATL interfaces, sets the return type for the property. |
| 53 | + For dual interfaces, `HRESULT` is always the return type, and select option is unavailable. |
| 54 | + For custom interfaces, you can select a return type from the list. `HRESULT` is still recommended, as it provides a standard way to return errors. |
| 55 | + |
| 56 | +- **Get function** |
| 57 | + |
| 58 | + For ATL interfaces, creates the `Get` method for retrieving the property value. Select **Get**, **Put**, or both. |
| 59 | + |
| 60 | +- **Put function** |
| 61 | + |
| 62 | + For ATL interfaces, creates the `Put` method for setting the property value. Select **Get**, **Put**, or both. If you select **Put function**, you can choose from the following two ways to implement the method: |
| 63 | + |
| 64 | + |Option|Description| |
| 65 | + |------------|-----------------| |
| 66 | + |**propput**|The [PropPut](../windows/attributes/propput.md) function returns a copy of the object. **propput** is the default and the most common way to make the property writable.| |
| 67 | + |**propputref**|The [PropPutRef](../windows/attributes/propputref.md) function returns a reference to the object, rather than returning the copy of the object itself. Consider using **propputref** option for objects, such as large structs or arrays, that may have initialization overhead.| |
| 68 | + |
| 69 | +- **Parameters** |
| 70 | + |
| 71 | + Displays the list of parameters added to the property. Each item in the list consists of the parameter name, parameter type, and attributes. |
| 72 | + |
| 73 | + `in` indicates that the parameter is passed from the calling procedure to the called procedure. |
| 74 | + `out` indicates that the pointer parameter is returned from the called procedure to the calling procedure (from the server to the client). |
| 75 | + |
| 76 | +- **+** |
| 77 | + |
| 78 | + Add a parameter. In **Parameters**, type the parameter type and name. For example, `int x`, and select **OK**. |
| 79 | + |
| 80 | +- **x** |
| 81 | + |
| 82 | + Removes the selected parameter from **Parameters**. |
| 83 | + |
| 84 | +- **Pencil icon** |
| 85 | + |
| 86 | + Edit the selected parameter. |
| 87 | + |
| 88 | +- **Attributes** |
| 89 | + |
| 90 | +1. `helpcontext` |
| 91 | + |
| 92 | + Specifies a context ID that lets the user view information about this property in the Help file. For more information, see [helpcontext](/windows/win32/Midl/helpcontext). |
| 93 | + |
| 94 | +1. `helpstring` |
| 95 | + |
| 96 | + Specifies a character string that's used to describe the element to which it applies. By default, it's set to **`property`** *Property name*. For more information, see [helpstring](/windows/win32/Midl/helpstring). |
| 97 | + |
| 98 | +1. `id` |
| 99 | + |
| 100 | + Sets the numerical identifier that identifies the property. This option isn't available for properties of custom interfaces. For more information, see [id](/windows/win32/Midl/id). |
| 101 | + |
| 102 | +- **Additional attributes** |
| 103 | + |
| 104 | +Keywords in the Microsoft Interface Definition Language (MIDL) are described in detail in the [MIDL language reference](/windows/win32/midl/midl-language-reference.md). |
| 105 | + |
| 106 | + |Option|Description| |
| 107 | + |------------|-----------------| |
| 108 | + |`bindable`|Indicates that the property supports data binding. For more information, see [bindable](/windows/win32/Midl/bindable).| |
| 109 | + |`defaultbind`|Indicates that this single, bindable property best represents the object. For more information, see [defaultbind](/windows/win32/Midl/defaultbind).| |
| 110 | + |`defaultcollelem`|Indicates that the property is an accessor function for an element of the default collection. For more information, see [defaultcollelem](/windows/win32/Midl/defaultcollelem).| |
| 111 | + |`displaybind`|Indicates that this property should be displayed to the user as bindable. For more information, see [displaybind](/windows/win32/Midl/displaybind).| |
| 112 | + |`hidden`|Indicates that the property exists but shouldn't be displayed in a user-oriented browser. For more information, see [hidden](/windows/win32/Midl/hidden).| |
| 113 | + |`immediatebind`|Indicates that the database will be notified immediately of all changes to this property of a data-bound object. For more information, see [immediatebind](/windows/win32/Midl/immediatebind).| |
| 114 | + |`local`|Specifies to the MIDL compiler that the property isn't remote. For more information, see [local](/windows/win32/Midl/local).| |
| 115 | + |`nonbrowsable`|Tags an interface or dispinterface member that shouldn't be displayed in a properties browser. For more information, see [nonbrowsable](/windows/win32/Midl/nonbrowsable).| |
| 116 | + |`requestedit`|Indicates that the property supports the `OnRequestEdit` notification. For more information, see [requestedit](/windows/win32/Midl/requestedit).| |
| 117 | + |`restricted`|Specifies that the property can't be called arbitrarily. For more information, see [restricted](/windows/win32/Midl/restricted).| |
| 118 | + |`source`|Indicates that a member of the property is a source of events. For more information, see [source](/windows/win32/Midl/source).| |
| 119 | + |
| 120 | +## **See also** |
| 121 | + |
| 122 | +[Add Property](adding-a-property-visual-cpp.md) |
0 commit comments