Saul Greenberg > courses > HCI topics > visual basic > tutorial 10

Tutorial 10
ActiveX Control Examples

• Introduction
• Example 1: Building to an OCX binary
• Example 2: Building as part of an EXE project (generally recommended)
• Example 3: Building either of the above helped by the ActiveX Control Wizard Interface

Introduction

The basic idea of the control as presented in all three of these examples is to demonstrate the basics in as simple a package as possible. As such, all I do is go through and make a useable control that is simply a button with reduced functionality. It has:

• 2 Events
  • Click (to demonstrate a simple event)
  • MouseDown (to demonstrate an event that contains parameters)
• 1 Property (to deonstrate how properties work for reading and writing)

I'll go through each method for building, assuming you already know the basics of Visual Basic. At the top of each one, I'll explain briefly advantages and disadvantages to using that method and why and where you might want to use them.

Example 1

• Download the Source Code for Example 1

To build an ActiveX control from scratch and compile it so that it is usable as a command button or a listbox is in other projects, you write the ActiveX Control and then compile it to an OCX file. The ocx file contains only the user controls that were part of the VB project you built it from and no extra stuff like forms or full programs. Think of simply having a library with button and a listbox in it, that would be the same idea. The advantage of this is that you can conveniently add it to any VB program you may start up from the components list. The disadvantage is that you can do this only provided that the machine you're working on (1) has that ocx file and (2) that ocx file is registered on the machine.

Now let's go through building this thing from scratch.

1. Start up Visual Basic 6.0.
2. On the opening dialog box, choose ActiveX Control and hit Open.

fig 1: new project dialog box

3. You get what looks like a blank grey background, that's the surface of your control. As you design that surface is how it will look when you draw it on a form later on. For now, all you need to do is add a command button to the control, so do that and make sure it's in the very top lefthand corner of the UserControl surface:

fig 2: control layout

4. The code for this is quite simple, and I'll go through it from top to bottom. There are two events we're going to provide to people using this control, so we declare them as such. The thing to note is that the Click event has no parameters (ie the idea is that it provides no information to someone using this control beyond that a "click" was fired) and that the MouseDown event has four parameters (ie, it will provide someone using this control with those four pieces of information to be used in whichever way is seen fit):

Option Explicit

' ================== HERE ARE SOME EVENTS
Event Click()
Event MouseDown(Button As Integer, Shift As Integer, X As Single, Y As Single)

5. The next section of code deals with the one property our button control will support, it's called Caption. To be able to read and write properties to a control, you have to provide a Get (which will be used to return the value of the property when it is requested externally) and a Let (which is used when someone wants to change the value of a property) function. There is also a Set function which can be used for complex objects instead of just simple data types (I'm pretty sure of this, remind me to check on it). The basic idea of these functions is that the let takes in a new string and just assigns it to the Caption property of the command button and the let just returns the current string found in the Caption property of the command button.

' ================== HERE ARE SOME PROPERTIES
Property Get Caption() As String
    Caption = Command1.Caption
End Property

Property Let Caption(newCap As String)
    Command1.Caption = newCap
End Property

6. The next two subs are just some stuff associated with the UserControl object. Similar to a Form in VB, a UserControl has a life and a death and a bunch of events and methods associated with that progression. In actuality, you have as much control over your user control as you do over a form in VB. Here's an example of a couple of these events being used to resize the button to be the size the developer draws the UserControl to and to set the initial caption of the button:

' ================== HERE ARE SOME USERCONTROL HANDLERS
Private Sub UserControl_Initialize()
    Command1.Caption = UserControl.Name
End Sub

Private Sub UserControl_Resize()
    Command1.Width = UserControl.Width
    Command1.Height = UserControl.Height
End Sub

7. Finally we have a couple of methods that simply handle events as fired by a command button. What happens in them is the acutal firing of the events as declared above so that they can be captured and handled by someone using the control. This is done using the RaiseEvent function. You'll notice that in the case of the Click event, no parameters are included except the name of the event that's being fired. In the case of the MouseDown event however, four parameters are supplied as in the declaration from above. In this simple example, I'm just forwarding the values as retrieved by the command button in the first place, but you can send back any information you wish as part of the event, which is important and useful to remember!

' ================== HERE IS THE ACTUAL WORK FOR THIS ACTIVEX CONTROL
Private Sub Command1_Click()
    RaiseEvent Click
End Sub

Private Sub Command1_MouseDown(Button As Integer, Shift As Integer, X As Single, Y As Single)
    RaiseEvent MouseDown(Button, Shift, X, Y)
End Sub

And we are done! To use this control in another VB project, all you need to do is build it into its compiled form, and then register the produced ocx file in the Windows Registry. It should then appear in the components list in VB as your UserControl was named (reminder, the default project name is "Project1" which can be changed in the project properties dialog box. Note that the name of your UserControl cannot match the name of the project as VB produces the OCX file and names it <project name>.ocx!!).

Notes for CPSC 581 at the U of C on registering:

• on your home machine, this will likely happen automatically when you compile the program (file->build <project>.ocx) and it will be included in component lists as soon as VB is restarted.
• on the lab machines, you will not have privileges to register the ocx file. Take note of where you create the OCX file when you go to build, it will still build that file and then complain about registering privileges. On your desktops, you have a couple of facilities called "register activex component" and "unregister activex component." All you need to do is drag your ocx file onto the "register" icon and it should register properly on the machine.

Example 2

• Download the Source Code for Example 2

For the purposes of CPSC 581, this will likely be the easiest for distribution purposes. As you make a standard VB EXE project, you can include other things in it: forms, code modules, class modules, user controls, etc. When you include a UserControl, you are including the same thing as an ActiveX control project. The advantage to this is purely convenience and ease of use. When you build your exe project, the user control will be included in the binary exe file that is produced. This is not so in the case of other controls that are simply included from the components list. For example, the code for a command button never appears anywhere in your exe even if you use one in your program. The distinct advantage of this is that there is no registering required for the ActiveX control, you can just use it. The disadvantage is that if you want to use it in other programs, you won't be able to as it's not included in the components list. Of course you could just duplicate the code as well.

1. Building this example is just as easy as above. First, start a regular VB exe project. Then, from the project menu, select "add user control," and then "User Control" from the following dialog.

fig 3: project menu

fig 4: add user control dialog

2. You'll get a similar UserControl layout for example one, and all you need to do is set it up to look the same again:

fig 5: control layout

3. Then, just add the code for it. It's exactly the same as in Example 1, so that's just reproduced here without the annotations of above for convenience sake:

Option Explicit

' ================== HERE ARE SOME EVENTS
Event Click()
Event MouseDown(Button As Integer, Shift As Integer, X As Single, Y As Single)

' ================== HERE ARE SOME PROPERTIES
Property Get Caption() As String
    Caption = Command1.Caption
End Property

Property Let Caption(newCap As String)
    Command1.Caption = newCap
End Property

' ================== HERE ARE SOME USERCONTROL HANDLERS
Private Sub UserControl_Initialize()
    Command1.Caption = UserControl.Name
End Sub

Private Sub UserControl_Resize()
    Command1.Width = UserControl.Width
    Command1.Height = UserControl.Height
End Sub

' ================== HERE IS THE ACTUAL WORK FOR THIS ACTIVEX CONTROL
Private Sub Command1_Click()
    RaiseEvent Click
End Sub

Private Sub Command1_MouseDown(Button As Integer, Shift As Integer, X As Single, Y As Single)
    RaiseEvent MouseDown(Button, Shift, X, Y)
End Sub

4. After the code is all there, close both the design window and code window for the user control and you'll see your user control added to the components toolbox. You can pick it and draw one on your form if you like:

fig 6: bitton in the toolbar!

Then you can use it just like you would any other normal control in the components list. For fun, if you download the example it just demonstrates the "click" event using a message box.

Example 3

• Download the Source Code for Example 3

The last way you can build controls is by using the help of the VB ActiveX Control Wizard Interface. Sounds impressive right? Well, it is because it makes a lot of free code for you, hehehe. The advantage of using this method over coding from scratch as was done in the above examples is that it generates extra stuff to do with saving properties and retrieving them later, although I won't go into the specifics of that here. Suffice it to say that it makes for less typing in a lot of cases and eliminates the possibility that you'll forget something (ie, you write a Let function for a property but not the Get one when you meant to have one!!). You can use the ActiveX Control Wizard to design controls for either of the build methods mentioned in the above two examples.

1. To do it, you design your control visually first, and then use the Wizard to generate Methods, Events, and Properties. So, get your control ready using whichever scheme you like and start the ActiveX Control Interface Wizard by going project->add user control and then selecting the VB ActiveX Control Interface Wizard from the dialog box that appears.

fig 7: project menu

fig 8: add user control dialog

2. Then, go follow the steps through the wizard so that your dialogs look as follows (it should be fairly self explanatory:

Step 1: Hahaha, turn off this screen in the future if you'd like! I usually do, hehehehe
Step 2: Stock properties, events, and methods. On this screen you can choose from a list of commonly used events, methods and properties that you might want to support. For this example, the ones you want are pictured in the diagram.
Step 3: Custom Interface elements. Here is where you can define your own events, methods, and properties. So if you wanted to have an event in your control called "Dude," here is where you'd define it.
Step 4: (I have never really used this screen for anything but can figure it out if requested to do so, hehehe)
Step 5: Here you can determine some properties for your interface elements including type, default values, read/write capabilities, and even a description to help a developer out. For example you could relate to a developer just what the String property "Dude" was for.
Step 6: And we are done, you can choose to view the summary report if you like, but it's mostly junk.

3. After that, you just need to modify the code that this thing made a little bit to support the rest of the functionality of the control. Check it out, all the code that you get for free is regular face, and everything I added to complete the control is included in boldface:

Option Explicit

'Default Property Values:
Const m_def_Caption = "Butoon"
'Property Variables:
Dim m_Caption As String
'Event Declarations:
Event Click()
Event MouseDown(Button As Integer, Shift As Integer, X As Single, Y As Single)

'added by mike
Private Sub Command1_Click()
    RaiseEvent Click
End Sub

'added by mike
Private Sub Command1_MouseDown(Button As Integer, Shift As Integer, X As Single, Y As Single)
    RaiseEvent MouseDown(Button, Shift, X, Y)
End Sub

'WARNING! DO NOT REMOVE OR MODIFY THE FOLLOWING COMMENTED LINES!
'MemberInfo=13,0,0,
Public Property Get Caption() As String
    Caption = m_Caption
End Property

Public Property Let Caption(ByVal New_Caption As String)
    m_Caption = New_Caption
    PropertyChanged "Caption"
    
    'added by mike:
    Command1.Caption = m_Caption
End Property

'Initialize Properties for User Control
Private Sub UserControl_InitProperties()
    m_Caption = UserControl.Name
    Command1.Caption = m_Caption
End Sub

'Load property values from storage
Private Sub UserControl_ReadProperties(PropBag As PropertyBag)
    m_Caption = PropBag.ReadProperty("Caption", m_def_Caption)
    Command1.Caption = m_Caption
End Sub

'added by mike
Private Sub UserControl_Resize()
    Command1.Height = UserControl.Height
    Command1.Width = UserControl.Width
End Sub

'Write property values to storage
Private Sub UserControl_WriteProperties(PropBag As PropertyBag)
    Call PropBag.WriteProperty("Caption", m_Caption, m_def_Caption)
End Sub

And we are allllllll done.