| Microsoft Office 2000/Visual Basic Programmer's Guide | |
The sample code in this section is taken from the DataComboBox.xls sample, which is available in the ODETools\V9\Samples\OPG\Samples\CH09 subfolder on the Office 2000 Developer CD-ROM. This sample includes a custom event named ItemAdded on a custom object named DataComboBox. Since creating and responding to a custom event requires code in several places, it may be useful for you to study and run this sample while reading this section.
The DataComboBox object wraps a combo box on a form in order to provide an additional event, the ItemAdded event, which the MSForms ComboBox control doesn't have. When the user enters a new item and chooses to add it to the list, the ItemAdded event occurs. The programmer can use the ItemAdded event procedure to run validation code before adding the item to the list. For example, the ItemAdded event procedure in the sample file checks to see whether the item already exists in the list. If it does, the event is cancelled and the item is not added.
To define a custom event in a class module, use the Event keyword. An event may be public or private and must be declared at the module level. It can have any number of arguments, but it can't return a value. The following statement defines the ItemAdded event in the DataComboBox class:
Public Event ItemAdded(strValue As String, _
blnCancel As Boolean)
After you've defined the event in the DataComboBox class module, you can declare a private module-level variable of type DataComboBox, declared by using the WithEvents keyword, in the module of the frmDataCombo form:
Private WithEvents mdcbCombo As DataComboBox
This declaration notifies VBA that the instance of the DataComboBox class that this variable points to will respond to events. Once you've added this variable declaration to the form's module, you can create the mdcbCombo_ItemAdded event procedure stub by using the module's Object and Procedure drop-down lists:
Private Sub mdcbCombo_ItemAdded(strValue As String, _
blnCancel As Boolean)
' Code that runs when event occurs.
End Sub
When the form loads, the code creates a new instance of the DataComboBox object and sets its custom ComboBox property, which is an object property, to point to the cboData combo box on the form:
Private Sub UserForm_Initialize()
' Create new instance of DataComboBox object.
Set mdcbCombo = New DataComboBox
' Set ComboBox property of DataComboBox object
' to point to combo box on form.
Set mdcbCombo.ComboBox = Me.cboData
End Sub
Note that the ComboBox object property is the key to wrapping the built-in ComboBox object within a custom class, as was discussed earlier in this chapter in "Creating Object Properties." The ComboBox property provides access to all the properties and methods of the built-in ComboBox object.
At this point, the event has been defined in the class module, and the form is set up to respond to the event when it occurs. The next step is to write the procedure that raises the event. This procedure must be in the same module in which the event is defined, namely the DataComboBox class module.
It's reasonable that a combo box would know how to add an item that the user has entered in the text portion of the combo box. There's no built-in way to do this for an MSForms ComboBox control, however, so the DataComboBox class provides one, a method named AddDataItem. When the form calls this method on an instance of the class, the method raises the ItemAdded event, giving the programmer an opportunity to respond through the event procedure and handle the event as needed. After the event procedure runs, if the event was not cancelled, the AddDataItem method adds the new item to the list.
Here's the code for the AddDataItem method. Note that the RaiseEvent statement raises the ItemAdded event and passes values for its arguments. When this line executes, the event procedure defined in the form's module runs.
Public Function AddDataItem(strValue As String)
' Raises ItemAdded event when user chooses to add
' item. If item already exists in list, event is
' cancelled. Otherwise new item is added to list.
Dim blnCancel As Boolean
' Initialize Boolean variable.
blnCancel = False
' Raise ItemAdded event, passing in new value
' and Boolean variable. Boolean variable is passed
' by reference, so event procedure may alter its
' value.
RaiseEvent ItemAdded(strValue, blnCancel)
' If ItemAdded event is cancelled, then exit.
' Otherwise add new item to list.
If blnCancel = False Then
Me.ComboBox.AddItem strValue
End If
End Function
Finally, there must be code that calls the AddDataItem method. In the sample file, this method is called from the Click event procedure of the cmdAdd command button:
Private Sub cmdAdd_Click()
Dim strValue As String
' Store value that's been typed into combo box.
strValue = Me.cboData.Text
' Call AddDataItem method of DataComboBox object.
mdcbCombo.AddDataItem strValue
End Sub
In summary, a command button's Click event procedure in the form's module calls the AddDataItem method of the DataComboBox object. The AddDataItem method raises the ItemAdded event, which in turn calls the combo box's ItemAdded event procedure in the form's module.
The ItemAdded event procedure in this example checks to make sure that the item doesn't already exist in the list and cancels the add operation if it does. You could put whatever code you wanted here, though, and it could be different code for different forms. For example, the ItemAdded event could include code to convert the entry to proper case, or it could trim additional spaces from the text entered, or it could write the entry to a database.