ActiveX Controls: Using Data Binding in an ActiveX Control

|  Overview |  How Do I |  FAQ |  |  Sample

One of the more powerful uses of ActiveX controls is data binding, which allows a property of the control to bind with a specific field in a database. When this control property is modified by the control user, the control notifies the database that the value has changed and requests that the record field be updated. The database then notifies the control of the success or failure of the request.

This article covers the control side of your task. Implementing the data binding interactions with the database is the responsibility of the control container. How you manage the database interactions in your container is beyond the scope of this documentation. How you prepare the control for data binding is explained in the rest of this article.

This article covers the following topics:

• How data binding works

• Defining a bindable property

How Data Binding Works

Data binding allows a database entry, such as a record field, to be linked to a property of an ActiveX control. This control is typically used in a form view and provides a visual interface to the current record state. The figure below shows a conceptual representation of this linkage. In this example, the ActiveX control is an edit box which has bound its Text property to the Name field of a record. When modifications are made to the control’s Text property, these changes are communicated to the database.

Conceptual Diagram of a Data Bound Control

When an ActiveX control property is bound, the developer must make sure that the control is able to send notifications to the database when the property changes. The notification is sent to an interface provided by the control container, which processes it and returns the database’s response to the control.

The COleControl class provides two member functions that make data binding an easy process to implement. The first function, is used to request permission to change the property value. , the second function, is called after the property value has been successfully changed.

Defining a Bindable Property

If the control was created using ControlWizard, data binding is automatically enabled. Once you have successfully compiled your ActiveX control, you can use ClassWizard to incorporate data binding. ClassWizard allows you to choose which properties to make bindable and provides several binding options.

The following procedure demonstrates adding a text property to an existing control that subclasses an edit box. This property can then be bound to a record field. The figure below shows the Data Binding dialog box.

The Data Binding Dialog Box

To add a bound property using ClassWizard

1. With your control project open, click ClassWizard on the View menu.

2. Click the Automation tab.

3. In the Class Name box, select the name of your control class.

4. Click Add Property.

5. In the External name box, type the external name of the property. For this example, use RecordName.

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

   Note   Data binding is not supported for properties implemented as member variables.

7. In the Type box, select the property’s type. For this example, select BSTR.

   Note   Do this step after setting the Implementation option. If you try to do it before, the BSTR type is not available in the Type box.

8. Type unique names for your Get and Set Functions or accept the default names.

9. Click OK to confirm your choices and close the Add Property dialog box.

10. Click Data Binding.

11. Select the Bindable Property check box.

12. Set any other data binding options you desire.

13. Click OK to confirm your choices and close the Data Binding dialog box.

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

After completing this process you will have a property called RecordName that can be bound to a string-valued field in a database.

Code Changes Related to Data Bound Property

Implementing a bound property requires code changes in some of the control project files.

The following code is added to the control declaration file (.H) between the dispatch map comments:

   afx_msg BSTR GetRecordName( );
   afx_msg void SetRecordName( LPCTSTR lpszNewValue );

In addition, changes will be made to the control implementation file. The following sample shows what would be added if you followed the example in the procedure:

BSTR CSampleCtrl::GetRecordName()
{
   CString strResult;
   // TODO: Add your property handler here

   return strResult.AllocSysString();
}

void CSampleCtrl::SetRecordName(LPCTSTR lpszNewValue)
{
   // TODO: Add your property handler here

   SetModifiedFlag( );
}

To fully implement the control data binding you have to modify the GetRecordName and SetRecordName functions. For example, in the SetRecordName function, you would make a call to BoundPropertyRequestEdit to obtain permission to change the value of the bound property. If it was successful, you would save the new value and handle any other actions needed before notifying the container that the property has changed. This notification would be done by calling BoundPropertyChanged. The following code sample demonstrates this:

void CSampleCtrl::SetRecordName( LPCTSTR lpszNewValue )
{
 if( !BoundPropertyRequestEdit( dispidRecordName) )
    SetNotPermitted( );
//TODO: Actually set property value.
 BoundPropertyChanged( dispidRecordName);
 SetModifiedFlag( );

}