MFC ActiveX Controls: Advanced Property Implementation

The new home for Visual Studio documentation is Visual Studio 2017 Documentation on docs.microsoft.com.

The latest version of this topic can be found at MFC ActiveX Controls: Advanced Property Implementation.

This article describes topics related to implementing advanced properties in an ActiveX control:

• Read-only and write-only properties

• Returning error codes from a property

Read-Only and Write-Only Properties

The Add Property Wizard provides a quick and easy method to implement read-only or write-only properties for the control.

To implement a read-only or write-only property

1. Load your control's project.

2. In Class View, expand the library node of your control.

3. Right-click the interface node for your control (the second node of the library node) to open the shortcut menu.

4. From the shortcut menu, click Add and then click Add Property.

   This opens the Add Property Wizard.

5. In the Property Name box, type the name of your property.

6. For Implementation Type, click Get/Set Methods.

7. In the Property Type box, select the proper type for the property.

8. If you want a read-only property, clear the Set function name. If you want a write-only property, clear the Get function name.

9. Click Finish.

When you do this, the Add Property Wizard inserts the function SetNotSupported or GetNotSupported in the dispatch map entry in place of a normal Set or Get function.

If you want to change an existing property to be read-only or write-only, you can edit the dispatch map manually and remove the unnecessary Set or Get function from the control class.

If you want a property to be conditionally read-only or write-only (for example, only when your control is operating in a particular mode), you can provide the Set or Get function, as normal, and call the SetNotSupported or GetNotSupported function where appropriate. For example:

void CMyAxUICtrl::SetMyProperty(SHORT newVal)
{
   AFX_MANAGE_STATE(AfxGetStaticModuleState());

   if (m_bReadOnlyMode)   //  some control-specific state
   {
      SetNotSupported();
   }
   else
   {
      m_iPropVal = newVal;   //  set property as normal
      SetModifiedFlag();
   }
}

This code sample calls SetNotSupported if the m_bReadOnlyMode data member is TRUE. If FALSE, then the property is set to the new value.

Returning Error Codes From a Property

To indicate that an error has occurred while attempting to get or set a property, use the COleControl::ThrowError function, which takes an SCODE (status code) as a parameter. You can use a predefined SCODE or define one of your own. For a list of predefined SCODEs and instructions for defining custom SCODEs, see Handling Errors in Your ActiveX Control in the article ActiveX controls: Advanced Topics.

Helper functions exist for the most common predefined SCODEs, such as COleControl::SetNotSupported, COleControl::GetNotSupported, and COleControl::SetNotPermitted.

For more information on reporting exceptions in other areas of the code, see COleControl::FireError and the section Handling Errors in Your ActiveX Control in the article ActiveX Controls: Advanced Topics.

See Also

MFC ActiveX Controls
MFC ActiveX Controls: Properties
MFC ActiveX Controls: Methods
COleControl Class