ActiveX Controls: Advanced Property Implementation

Home |  Overview |  How Do I |  FAQ |  Tutorial |  Sample

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

Read-only and Write-only Properties

ClassWizard 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 the control project.

  2. On the View menu, click ClassWizard.

  3. Click the Automation tab.

  4. Click the control’s class from the Class name box.

  5. Click Add Property.

  6. In the External name box, type the name of your property.

  7. In the Implementation box, click Get/Set Methods.

  8. In the Type box, select the proper type for the property.

  9. If you want a read-only property, clear the Set function name specified by ClassWizard. If you want a write-only property, clear the Get function name.

  10. Click OK to close the Add Property dialog box.

  11. Click OK to confirm your choices and close ClassWizard.

When you do this, ClassWizard 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- 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 CSampleCtrl::SetMyProperty( short propVal )
{
    if ( m_bReadOnlyMode )   //  some control-specific state
        SetNotSupported( );
    else
        m_ipropVal = propVal;   //  set property as normal
}

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.

Note   ThrowError is meant to be used only as a means of returning an error from within a property’s Get or Set function or an automation method. These are the only times that the appropriate exception handler will be present on the stack.

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   ActiveX Controls: Properties, ActiveX Controls: Methods, COleControl