Designing ActiveX controls

motivation

Now that you have some background in VB's approach to OOP, you no doubt have some more questions.  The class module has some promise as a background data structure, but it is harder to see how it would be used in actual programs.  VB programmers are used to a form of objects, but they prefer to work with controls.  Controls are a subset of classes, that have some specific important characteristics.  They have some kind of visual interface (at least at design time), they are installable into the toolbar, and they can be accessed through the property window.  All VB controls have done these things since VB began.  However, the way they have done this, and the internal workings, have changed dramatically.  The latest incarnation of the VB control is called the ActiveX control.

so, what's so special about ActiveX?

ActiveX is the trade name for a technology first developed by Microsoft in 1997.  It was an attempt to integrate several different technologies:
• VB controls, which had been called VBXs and and later OCXs
• The COM object model - the underlying model of the Microsoft world
• OLE, Microsoft's Object Linking and Embedding technology, which was designed to enable applications to communicate easily with each other
• VBScript - a simplified version of VB that was intended to be the 'glue' between activeX objects
As you can see, these earlier technologies were all very specific to Microsoft, and ActiveX is as well.  It is slowly being adapted for some other uses, but it still is largely an MS Windows - locked technology.

An ActiveX control can be 'dropped' into a form like any other control.  Controls are not specific to VB, but can also be dropped into VBA forms in other Office applications.  Parts of programs, like the Word Art feature packaged with Word, can be exposed as ActiveX objects and installed in any container that can hold ActiveX, including VB forms.  ActiveX controls can be written either in Visual C++ or in VB.  They can also be used by either language.  (J++ can incorporate ActiveX, but the platform - independant versions can not, as of this writing.)

Perhaps the most exciting part of this technology from our point of view is that it gives us a framework to extend our classes into actual controls that can be used by our VB projects.

Ok.  let's make one.

Take a look at this code:
Private Sub picColor_Click()
  Static colorNum As Integer
  colorNum = colorNum + 1
  If colorNum > 15 Then colorNum = 0
  picColor.BackColor = QBColor(colorNum)
End Sub

With just a small amount of study, you no doubt figured out what this code does.  It reacts whenever a user clicks on a picture box, and it increments to the next qbcolor, recycling at 15.  This is a pretty meaningless piece of code, yet it has some value as an example.

Let's make an ActiveX control with this same functionality.

setting up the workspace

To set things up, we go in to VB, and start it up exactly like usual.  Create a standard exe project.  This exe is not the eventual goal of our work, but it is the context within which we will test our control.  Stay with me and you'll get it.

Add a user control from the project menu.  You will see the typical list of templates. Go with the generic 'user control' for now.  As usual, the other options will be handy later, but often perform superflous features that are of little values when we're trying to orient ourselves.

When you look at the project window now, you will see that you now have two projects open at once.  This has only been possible in the latest versions of VB, but it is necessary for ActiveX programming.  What's going on here is we're actually writing two distinct programs.  One of them (the exe) happens to use the other.  (or will, when we add the code).

Note that the user control does have a visual interface which looks suspicously like a form, although it is not.

designing the control

Make sure you are in the control's workspace, then add a picture box to the upper left corner of the workspace.  Name it picColor, and give it the code above.  If you try to 'run', nothing will happen yet.  You will see the empty form for the exe project, but since it has no code, it is kind of meaningless.

adding the control to the form

In order to test a control, you must close out its editor and load it into some kind of container.  The easiest container to work with is a vb project, which is why we opened one up.  First, though, we must 'close up' the ActiveX control so it is in a stable state.  The easiest way to do this seems to be shutting all windows in the main editing area which have anything to do with the activeX control.  When you do this, the custom control icon on the toolbar will no longer be grayed out.  It will look like this:

Go back to the form, choose the user control icon from the toolbar, and draw the control on your form.
If you look at the properties box while your control is selected, you will see that it has a normal set of the most essential properties.
Check to see if it has any methods exposed.  You will see that a very few methods are there, but the set is by no means complete.
For this example, do not add any code to your form!!
Run the program, and if all went well, your program now has the functionality of our custom control, without requiring a single line of code from the form.

Let's have a more realistic example...

This is interesting, but it does not really act all that much like a real control.  We expect a control to have properties, events, and methods.  Let's make a more complex color chooser that works like this...

This form contains ONLY one control, a color scroller.  This control is a user control, which contains a picture box and a horizontal scrollbar.  The scrollbar contains this code:
  picColor.BackColor = QBColor(scrColor.Value)
The control does change colors, but it does not really interact with the outside form.

It would be great if the programmer could write this code in her form:
sub colorScroll1_change()
  form1.backColor = colorScroll1.color
end sub

In order for this custom control to be of any use, it ought to expose some kind of color property, so the form author can set a color based on whatever the user selected. The purpose of this control is to shield the programmer from worrying about qbColors. In addition to a color property, we ought to have a few other standard properties, such as enabled, top and left, visible, and so on.
We will also need to have some sort of event mechanism.  The programmer will be expecting a change event, so we ought to provide one.

The activeX control interface wizard

The process of adding control interfaces to activeX controls is a bit tedious, so Microsoft provides a wizard to help.  The wizard is only useful after we have defined all the controls that will make up the final custom control.  Use the Add - ins manager to invoke the wizard.  The first page looks like this:


The left hand panel contains a bunch of pre-defined properties, events, and methods.  The right hand panel consists of the set of these pre-defined methods that will be used for your control.  Note that I removed all the properties, and all methods except 'enabled'.  I wanted to see what happens when I leave one.  The property I really want (color) does not exist on the list.  Neither does the change event.  The next screen will allow me to add these custom members.



This form has a place to list any custom members.  Note that the screen shot was taken AFTER I had added some members.  When you click on the New button, you will see a little dialog like this:


It's pretty straightforward, as you can see.  When we're done adding members, we will go on to the next screen of the wizard...
 



As you can see, this screen allows us to 'map' members of the custom control to similar members of the constituent controls.  In many cases, a member of the custom control will directly correlate with a member of one of the controls on the custom control.  In this example, all three of my members will have an obvious mapping relationship, although you will see that the wizard does not always get this right.
The change event of the colorScroller should be related to the change event of the scrollbar inside the scroller.  Likewise, the color of the scroller will always have the same value as the foreColor property of the picture box.  The enabled property can be tied to the enabled property of the userControl environment itself (the closest analogy to a form in activeX control design). It is up to the programmer to ensure that sensible mapping is done.  We shouldn't try to map a color property to the left property of some constituent control, for example, because these things are not the same type of information.  Generally, your control members will be mapped to constituent members with the same or very similar names.  This is the case in our control.

When we hit next, we come to the finished screen.  This has an option to print out instructions for testing the control.  These instructions are useful but can be obtuse.  Read them, but don't be worried if you don't understand the whole thing.

The code:

Remember, our original control had only one line of code in it!
  picColor.BackColor = QBColor(scrColor.Value)
When we return from the wizard, we will see that it added ALL kinds of mysterious stuff to our control.  Here is a listing of the control code:

'Event Declarations:
Event Change() 'MappingInfo=scrColor,scrColor,-1,Change

Private Sub scrColor_Change()
    RaiseEvent Change
  picColor.BackColor = QBColor(scrColor.Value)
End Sub

'WARNING! DO NOT REMOVE OR MODIFY THE FOLLOWING COMMENTED LINES!
'MappingInfo=UserControl,UserControl,-1,Enabled
Public Property Get Enabled() As Boolean
    Enabled = UserControl.Enabled
End Property

Public Property Let Enabled(ByVal New_Enabled As Boolean)
    UserControl.Enabled() = New_Enabled
    PropertyChanged "Enabled"
End Property

'WARNING! DO NOT REMOVE OR MODIFY THE FOLLOWING COMMENTED LINES!
'MappingInfo=picColor,picColor,-1,ForeColor
Public Property Get color() As OLE_COLOR
    color = picColor.ForeColor
End Property

Public Property Let color(ByVal New_color As OLE_COLOR)
    picColor.ForeColor() = New_color
    PropertyChanged "color"
End Property

'Load property values from storage
Private Sub UserControl_ReadProperties(PropBag As PropertyBag)

    UserControl.Enabled = PropBag.ReadProperty("Enabled", True)
    picColor.ForeColor = PropBag.ReadProperty("color", &H80000012)
End Sub

'Write property values to storage
Private Sub UserControl_WriteProperties(PropBag As PropertyBag)

    Call PropBag.WriteProperty("Enabled", UserControl.Enabled, True)
    Call PropBag.WriteProperty("color", picColor.ForeColor, &H80000012)
End Sub

The original line is still there, in the scrColor_change event, but there's a lot of other stuff going on as well.  Let's take a look at it.

Event code

The Event Change() declaration in the general area was a declaration that somewhere in the code, this object would be raising an event.  Be careful how you think of events here.  Before, we have only been consumers of controls.  We never raised an event, we only responded to the event.  In controls, when we raise an event, we send a message to the calling program that something has happened, and we provide functionality so that the programmer can add appropriate code to deal with the event.  The change event will be raised as part of the scrColor_change event.  What that means is this:  we are encapsulating the change event of the scroll bar, handling some stuff internally, then raising an event warning, telling whatever program is using this control that a change event has occurred.  The programmer can then respond to that change event.

When we test this code in a moment, we will see that it does not work perfectly.  Look carefully at the relationship between the change event of the scrollbar and the change event of the object, and see if you can guess what the problem will be.

Properties code

As you can see, all the code that we intended as properties has been given set and let procedures.  As usual, we can't trust the defaults, but they seem to be pretty close. One thing we may want to change:  Either color ought to be a read - only property (remember how to do that?) or we will need to add code to the property set of color so that it automatically changes the color of the picture box and the value of the scrollbar.

ReadProperties and WriteProperties

These two built-in events occur as the control is created, duplicated, and destroyed.  They transfer the properties of the class back to an object called the propertybag.  These allow for the transfer of information generated in design time to the control instance in run-time.  Generally you can leave these methods alone.  Likewise, you can ignore the mappingInfo comments that were automatically generated by the code, but DO NOT delete them.

Testing the program

To test this bad boy, we need to go back to the form, add an instance of this control (if it isn't already there), and put some code in its change event.  (There wasn't a change event before, but there ought to be one now.)  Remember, the form code was supposed to be this:

sub colorScroll1_change()
  form1.backColor = colorScroll1.color
end sub

When we test the program, it does not work correctly!!!
When I ran it, I always got the form color changed to black, which is qbColor zero.  Interestingly, When I tried this with VB5, the results were wrong in a different way.  The color would change, but the form color would always lag behind the scrollbar by one value.

The soloution can be found by looking closely at the scrColor_change event in the control code.  There are two minor problems here.

 After playing with debug.print, it became obvious that the color value was not automatically changing.  Sure, we told the wizard to make picScroller.color integrated with picColor.foreColor, but it isn't happening properly.  We'll need to give it a hand.  Apparently, the property set of the scroller is not being called, so we'll force it by changing it as well as changing the color of the picture box.  Here's my new code for scrColor_change()

  RaiseEvent Change
  picColor.BackColor = QBColor(scrColor.Value)
  Me.color = picColor.BackColor   ' I added this

This is a little better, but it causes the 'lag' behaviour that we saw in the VB5 version.  When my scrollbar is on color 2, my form is on color 1.  The form color is always one behind the scroll color.

The wizard put the raiseEvent call at the BEGINNING of the code.  This  tells the calling program to evaluate a change event before we have changed anything at this level.  Clearly this is not correct.  The raiseEvent should be the last thing this code does.  After we move it to the bottom, we are ensured that the values have changed BEFORE the form gets a chance to deal with the colorScroller_change event.

Here's my final version of the code for scrColor_change():

Private Sub scrColor_Change()
  picColor.BackColor = QBColor(scrColor.Value)
  Me.color = picColor.BackColor   ' I added this
  RaiseEvent Change               'I moved this to the bottom
End Sub

Everything else was left alone.

Let's make the airplane an activeX control!!

As you have no doubt surmised, the airplane we used in the last chapter would have made a fine activeX control.  It should certainly act like an object, but it ought to also have a visual interface.  We faked an interface, but it was not very natural.
Here's how we convert the airplane class.

making the control

It would be tempting to try to actually convert the code from the class module, but that would probably be more trouble than it is worth.  The important part of the airplane is the pseudocode, and it will actually be easier to re-create the framework from scratch as a control than to convert it.  Besides, some of our properties will need to be re-thought.  The good news is that our methods could simply be copied and pasted.