VBCOM TUTORIAL(2)

Object-based Programming

Introduction

COM programming is based on an object-oriented style of programming.  In VB, this means the use of classes and class-based object references.  If you are comfortable defining your own classes with logical properties and methods, and then using these classes to instantiate and manipulate objects, you can safely skip this section and continue the tutorial here.   Otherwise, let's begin! 

We will study object-based programming in the context of an example:  a form-based progress indicator class called CProgress.   Here's a picture of this class in action (you should see this for yourself by running the application /VBCOM/Demos/Class-based Progress Indicator/App.exe;   if you have not already done so, you can download the labs from the Setup page ):

Note the naming convention --- classes always being with a C.  It will be helpful if you also think of the C as standing for a concrete class, i.e. a class that can be turned into a run-time object that fulfills some function.

First, a bit of terminology.  A class is compile-time entity that a programmers writes.  In VB, a class is produced by adding a Class Module to your project.   A class may contain zero or more members, where a member is either a property (think of it as a variable) or a method (subroutine or function).  At run-time, you instantiate a class to produce an object that resides in memory.   In fact, you can instantiate the same class over and over again, each time producing a distinct object.  Finally, to facilitate discussion, we will use the terms client and server to denote two objects that are interacting, in particular where the client object is accessing a property or invoking a method on the server object:

Using the Class CProgress

The class is quite simple in design, having only one public property and two public methods:

	Public Value As Integer	'** percentage done
	Public Sub Show()	'** show the progress form
	Public Sub Hide()	'** hide the progress form

When this class is instantiated into an object, the Value of the object represents the current status of the progress indicator, e.g. 40 (denoting 40%).  By changing this value, the client can show progress.  The object's methods, Show and Hide, are invoked by the client to draw and erase the progress indicator form, respectively.   Altogether, this list of public properties and methods denotes the interface between clients and CProgress servers. 

At this point, let's look at some sample client code which instantiates and uses the CProgress class.  If you haven't already, open the supplied VB project /VBCOM/Demos/Class-based Progress Indicator/App.vbp and view the code in the cmdProgress button of the main form:

	Dim progress As CProgress	'** object reference to
		'**  CProgress instance
	Dim i As Integer, _
	j As Variant
	Set progress = _
	New CProgress	'** new instance of CProgress

The first line declares an object reference variable (a pointer in C++ parlance) of type CProgress.  Initially, an object reference variable points to no object, and thus has the value Nothing.  The third line uses VB's New operator to instantiate an object of class CProgress, and then sets the object reference variable progress to this new instance.  At this point we have:

The code continues by displaying the progress indicator form, and then executing a loop which simulates a long-running operation:

	progress.Show	'** invoke Show method
	For i = 1 To 10
	progress.Value = _
	progress.Value + 10	'** update by 10%
	For j = 1 To 1000000: Next j	'** pause to simulate activity
	Next i

Each time through the loop, progress increases by 10%.  Finally, once the loop completes, the progress indicator form is erased from the screen and the progress variable reset to Nothing:

	progress.Hide	'** invoke Hide method
	Set progress = Nothing	'** explicitly destroy instance

This last step is not strictly necessary, since VB will reset the variable to Nothing automatically once it goes out of scope.  However, it is important to note that the number of references to an object determines the lifetime of that object, i.e. the duration it exists in memory.  By setting progress to Nothing we are explicitly reducing the reference count of that object by 1.  Once an object's count reaches 0, it is destroyed.  Thus, in the example above, the object is immediately destroyed after the Set statement is executed.

Implementing the Class CProgress

If you haven't done so already, open the supplied VB project /VBCOM/Demos/Class-based Progress Indicator/App.vbp and view the code in the Class Module CProgress (stored in the file CProgress.cls).  Using VB's browser (F2), the class is summarized as follows:

The class actually contains two properties and four methods, although the first 3 listed above are private to the class (and thus accessible only to VB and the object itself).  The private property frm is used by the object to hold a reference to the Form instance containing the progress indicator.  This form is created in the method Class_Initialize, which is called automatically by VB whenever a new CProgress object is instantiated.  Likewise, the form is destroyed in the method Class_Terminate, called automatically when the object's reference count reaches 0.  Here's the relevant code from the class CProgress: 

	Option Explicit
	Private frm As Form	'** object reference to progress form
	Private Sub Class_Initialize()
	Set frm = New frmProgress	'** create a new instance of frmProgres
	Me.Value = 0	'** initialize our value to 0%
	End Sub
	Private Sub Class_Terminate()
	Unload frm	'** destroy progress form instance
	Set frm = Nothing
	End Sub

In this case, the method Class_Initialize is called behind the scenes in response to the client executing New:

	Set progress = New CProgress	'** create a new
		'**  instance of CProgress

Thus, when developing a class, use the Class_Initialize method to initialize the server for upcoming client use.  As for Class_Terminate, in this case the method is called when the client clears the last reference to the server:

Set progress = Nothing

'** explicitly destroy instance

Therefore, use the Class_Terminate method to cleanup (close files, destroy helper objects, etc.) before the server is gone for good. 

Now for the public interface of CProgress:  Value, Show and Hide.  Firstly, the Value property is not implemented using an integer variable, but instead is a logical property physically realized by appropriate Get and Let methods (look closely at the bottom pane of the browser window above).  Logical properties offer many benefits:   validation, the ability to take action when a property changes, read-only data, etc.  However, a stronger motivation is that COM simply does not allow a class to contain public data properties.  In a COM-compatible class, the only public members may be methods. 

Ignoring COM for the moment, a logical Value property makes sense in this situation since the server needs to update the progress indicator in response to a change in value.  The Let method is used to capture a write to the logical property, much like the Let statement in VBA assigns a new value to a variable.  Note that the new value is passed as a parameter to the method:

	Public Property Let Value(ByVal percentage As Integer)
	frm.pbarProgress.Value = percentage	'** update progress bar
	frm.lblPercentage.Caption = _
	CStr(percentage) & "%"	'** update label
	frm.Refresh	'** redraw form
	End Property

The new value is simply assigned to the underlying Windows 95 ProgressBar control on the progress form, as well as written to a label.  In order for the client to be able to read the current progress value, a corresponding Get method is also provided:

	Public Property Get Value() As Integer
	'** return current state of progress bar
	Value = frm.pbarProgress.Value
	End Property

Get methods are actually functions which return the current value of the logical property. 

The final two members of CProgress are the Show and Hide methods.  These are perhaps the easiest of the bunch, since their function is obvious:

	Public Sub Show()
	frm.Show	'** show form and redraw
	frm.Refresh
	End Sub
	Public Sub Hide()
	frm.Hide	'** erase form but leave form object in memory
	End Sub

That's it, the class CProgress is now completely implemented!

Classes vs. Instances

Before we begin our discussion of COM, let's review the notion of  classes, and instances of classes.  Consider the following client code:

	Dim p1 As CProgress, p2 As CProgress, p3 As CProgress

	Set p1 = New CProgress
	Set p2 = New CProgress
	Set p3 = New CProgress
	p1.Value = 40
	p2.Value = 5
	p3.Value = 99
	p1.Show
	p2.Show
	p2.Hide
	Stop	'** pause client and activate the debugger

How many instances of CProgress exist in memory?  Three!  How many progress indicator forms exist in memory (i.e. instances of frmProgress)?  Three!  How many of these form instances are visible on the screen?  One!  Okay, now you're ready to start the first lesson on.