Click Here to Install Silverlight*
United StatesChange|All Microsoft Sites
|Developer Centers|Library|Downloads|Code Center|Subscriptions|MSDN Worldwide
Search for

Advanced Search
MSDN Home > MSJ > March 1997
March 1997

Visual Basic 5.0 Relieves the Pain and Discomfort of ActiveX Control Creation, Part II

The distinction between classic and ActiveX events is important-classic events received by your control are opportunities for your code to do something interesting; ActiveX events your control raises provide opportunities for the developer using your control to do something interesting.

Guy Eddon and Henry Eddon

This article assumes you're familiar with Visual Basic and the Internet.

Code for this article: VB5Part2.exe (6KB)
Guy and Henry are working on a book entitled Active Visual Basic 5 to be published by Microsoft Press. Both can be reached at

In the first part of our series, (February 1997) we discussed some of the new features of Visual Basic® 5.0 and then dived right into the details of the ActiveX component programming features. We covered properties in extensive detail—they are the data stored inside an ActiveX component that is exposed to the component's container via the standard ActiveX interfaces. Typical examples of properties include simple things such as the color of the control and more complex data, such as text strings.
In the conclusion to this series, we'll look at the functions stored inside an ActiveX component—more commonly known as methods. We will also look into events, which are calls to and from the methods, and we will explain how you can write ActiveX components that work in both standalone Visual Basic applications and Web pages. So let's pick up where we left off and start with methods.


Methods are procedures built into a control that operate upon it. You can implement methods for ActiveX controls by adding Public Sub and Function procedures to the Declarations section of your control. You can write any method you want, but it is a good idea to implement some of the standard methods that seem to be found in pretty much every ActiveX control. If you have written a method that prints, use a standard method name of "Print," versus something custom like "MyOutput." How can you find a list of standard method names? The control wizard presents a list of properties, events, and methods (PEMs) that most controls expose. Additionally, it displays a list of PEMs found on any controls upon which you are basing controls.

Raising Events from Controls

Before we go on, we need to hammer down some events vocabulary. Ever since Visual Basic 1.0, programmers have used events, properties, and methods, but now we have ActiveX events, properties, and methods. An example of the classic Visual Basic event happens when you click on a button—you get your Private Sub Command1_Click style event. An ActiveX event is different, though. The event is not sent to your control like the classic Visual Basic event. Instead, your control sends the event to its container. Inside the classic Command1_Click event handler code (actually, anywhere in your code, but generally in a classic event handler), you can "raise" an ActiveX event. This means you send an ActiveX event to the container. Of course, to make things interesting, you would also name this ActiveX event Click.
It is important to distinguish between the classic events received by your control and the ActiveX events your control raises. Classic events received by your control are opportunities for your code to do something interesting; ActiveX events your control raises provide opportunities for the developer using your control to do something interesting. Developers using your control think of properties and methods as inbound actions and ActiveX events as outbound. Methods are invoked by developers using your control, while ActiveX events originate in your control and are propagated outward to the developer. This gives the developer using your control a chance to execute code in response to something that happens inside your control.
Two basic steps are required to raise an event from your control. First, you must declare the event itself, using a statement such as the following:

 Public Event MyEventName()
Next, you use the RaiseEvent statement to fire the event at the desired time with code like

 RaiseEvent MyEventName
The RaiseEvent statement provides functionality similar to simply calling a procedure. When calling a procedure, the procedure must actually exist. Event procedures, on the other hand, cause no errors if they are not implemented—the event is simply ignored.
It is also possible to raise events that provide parameters to the event procedure being called. This is useful with events such as MouseMove that require more information about the event that occurred—in this case the current mouse coordinates. To implement your own custom event with parameters, simply declare the event as something like this:

 Public Event MyEventName(MyParameter As Integer)
If you want to raise it with a parameter value of, say, 100, just call it like this:

 RaiseEvent MyEventName(100)
The control's container may provide additional events beyond those you define for the benefit of developers using your control. Visual Basic's Extender object automatically raises four events on behalf of ActiveX controls: DragDrop, DragOver, GotFocus, and LostFocus. It is recommended that most controls raise Click, DblClick, KeyDown, KeyPress, KeyUp, MouseDown, MouseMove, and MouseUp events. It is also a good idea to implement events commonly found on controls that provide functionality similar to yours—such as a scroll event if your control has a scrollbar.
Errors should never be raised within an event procedure, since there is nowhere for these errors to be trapped. For example, the Click event is fired when the user clicks on a control. If the control raises an error in response to this event, the container of the form never has a chance to respond. Visual Basic will simply report the errors and kill the application.

Procedure Attributes

The majority of advanced control features in Visual Basic are available in the deceptively simple Procedure Attributes dialog box (see Figure 1), accessed from the Tools menu. Once you click the Advanced button, the dialog expands and you find yourself staring at extra queries you have to make decisions about. The Procedure Attributes dialog box allows you to control settings for the various procedures of your control. Remember that properties, methods, and events are all implemented as procedures, so this dialog box is used for all three of these items. Some of the settings will have different effects when applied to different types of procedures, and some areas of this dialog box apply exclusively to either properties or methods.

Figure 1 Procedure Attributes dialog box
Figure 1 Procedure Attributes dialog box

The Procedure Attributes dialog box is subdivided into four regions, which we'll call name, property, attributes, and data binding. The name section deals with selecting, describing, and identifying specific procedures of your ActiveX control. The property region allows you to set property identification numbers, property pages, and property categories. The attributes region specifies where the property is displayed and allows you to set defaults. The data binding region is used to control Visual Basic's data-bound control model.
The Name box is where you select a procedure to work within the Procedure Attributes dialog box. All settings in the Procedure Attributes dialog box affect the current procedure referenced in the Name box. Click the drop-down button on the Name box and scan the list of your procedures. For the purposes of the Procedure Attributes dialog box, procedures include properties, methods, and events.
Once you select a procedure to work with in the Name box, you can type helpful text describing this procedure in the Description box. The text contained in the Description box will appear at the bottom of the Object Browser when the user selects the item. If the selected procedure is a property, the description text will also appear at the bottom of the Properties window.
The Help Context ID box lets you specify an identification number for the selected procedure. The Help Context ID should match the identification number of the correct topic in the help file. This will allow the Object Browser and the Properties window to display context-sensitive help for that item when the F1 key is pressed. The Project Help File box will display the help file chosen for the Visual Basic project via the Help File Name box of the Project Properties dialog box.
The Procedure ID box lets you select the type of procedure you are creating. Every property, method, and event in your type library has a procedure ID. Some have standard procedure IDs defined by the ActiveX control specification. It is always a good idea to assign the standard procedure ID to a property, method, or event, assuming there is one.
For example, if you have a Caption property for your control, it would be advisable to set its procedure ID to Caption. Assigning a standard procedure ID to a procedure tells Visual Basic the purpose of the procedure in your program. In some cases, this allowsVisual Basic to enable special behavior for that property, method, or event.
Every procedure can have only one procedure ID assigned, and no other procedure can have the same procedure ID. Note that if you do not change the default procedure ID from None, Visual Basic will assign one automatically. If you've worked with Visual C++, you'll recognize procedure IDs as the Visual Basic equivalent of an IDispatch interface identification number, or DISPID.
The standard procedure IDs for properties are Default, Appearance, AutoSize, BackColor, BackStyle, BorderColor, BorderStyle, BorderWidth, Caption, DrawMode, DrawStyle, DrawWidth, Enabled, FillColor, FillStyle, Font, ForeColor, hWnd, TabStop, and Text. For methods you can choose from Default, AboutBox, and Refresh. For events you can choose from Click, DblClick, KeyDown, KeyPress, KeyUp, MouseDown, MouseMove, MouseUp, and Error.

Property Pages

Simple properties created with public variables or property procedures appear in the Properties window automatically, allowing the user to browse and set them. Sometimes, in more complex controls, a long list of properties appears in the Properties window that relate to one another in a manner not clear to the user. Property pages solve this problem. A tabbed dialog box holds a property page, often connected to the Custom property of a control. When the user double-clicks on the Custom property, the property page dialog box is displayed, allowing the user to set properties.
Select Add Property Page from the Project menu to add a property page to an ActiveX control. Then, in the Procedure Attributes dialog box, select the property page from the "Use this Page in Property Browser" dropdown list. Now, whenever the user double-clicks on the specified property, the property page dialog box is displayed automatically.

Property Category

The Properties window in Visual Basic has two tabs, one listing all of a control's properties in alphabetical order, and one grouping the properties by category, according to functionality. You can assign each of your control's properties to a particular group by using the Property Category box, which lists the standard categories: Appearance, Behavior, Data, DDE, Font, List, Misc, Position, Scale, and Text. You may either select from this list or create a new category by typing the new name directly into the Property Category box. Assigning categories is highly recommended; if you don't, all properties will be in the Misc group. As a general suggestion, look at other controls containing properties similar to those exposed by your control, and select your categories similarly. The first time, you may have a tendency to create too many new categories. Soon you'll realize that it is much easier to assign properties to existing categories, and that most necessary categories already exist.


In the Attributes section of the dialog box, you can control certain attributes of the procedure in question. The three choices are "Hide this member," "User Interface Default," and "Don't show in Property Browser." Checking the "Hide this member" box hides the item from view entirely. Properties will not appear in the Properties window, and neither properties nor methods will appear in the Statement Builder. (The Statement Builder automatically provides a popup list of applicable properties, methods, and events in the Code window.) Properties, methods, and events will still appear in the Object Browser because they are still part of the control's type library. This selection is often made to phase out particular items of a control's interface in successive versions of the software. Programs that rely on these properties, methods, and events will still work, but new software is unlikely to use them since they are not easily available.
For properties and events, checking the "User Interface Default" box makes this the default property highlighted in the Properties window, or the default event procedure displayed in the Code window. The "Don't show in Property Browser" box hides a property from the Properties window, effectively making this property available only at runtime.

Data Binding

The TextBox control is a standard example of a control that can be bound to a Data control. You can also create controls that can be bound to a Data control in the same manner as the TextBox control. Visual Basic enables you to do this by marking properties of your control as bindable. A developer can then associate bindable properties with database fields, making it easier to use your control in a database application. First, the "Property is data bound" box must be checked. This automatically provides your code with a DataBindings property and dialog box, which allows the user to associate properties with data fields. Then you can choose among the "This property binds to DataField," "Show this property in the Bindings collection," and "Property will call CanPropertyChange before changing" boxes.

ActiveX Controls for the Internet

Now let's focus on creating ActiveX controls targeted for the Internet in Visual Basic. By this we mean an ActiveX control that runs in a Web browser. How do controls get into a Web browser? While slightly more difficult than placing a control on a Visual Basic form, it's relatively straightforward: simply add an <OBJECT> tag to the HTML document and your control will appear.

 <OBJECT ID="MyControl" WIDTH=100 HEIGHT=50
         <PARAM NAME="MyProperty" value="MyValue">
For some types of controls, such as buttons and labels, this is sufficient; nothing special is necessary to Internet-enable the control.

Asynchronous Downloading

Designing software for the Internet requires a slight modification in the way most people think about writing programs. When you write software for the Internet it is possible that your code will be downloaded dynamically. Even if your code is already on the user's computer, it will probably need to download data.
To avoid stalling the user interface and other components, applications generally try to perform any time-consuming download operations asynchronously. This means that you start a particular downloading task, continue processing other work, and then are notified when the downloading job has been completed. The Asynchronous Moniker Specification, part of the ActiveX SDK, was developed to provide this type of functionality. Microsoft has provided this functionality to ActiveX controls written in Visual Basic via the AsyncRead and CancelAsyncRead methods and the AsyncReadComplete event of the UserControl object.
In general, the asynchronous download feature of Visual Basic is intended to download data into properties of a control. The AsyncRead method is used to initiate an asynchronous download of a property. This call returns immediately and downloading proceeds in the background, leaving your control free to do any other work. The AsyncReadComplete event will be fired at your control when the entire property data has finished downloading. This notifies your program that the data is ready for use. The CancelAsyncRead method can obviously be used to cancel the request during the download process.
If your control is running inside of a Web browser like Microsoft
® Internet Explorer, then a connection to the Internet is probably available for the data to be downloaded. But what happens if your control is being used on a form of a Visual Basic program? Well, assuming the user has the necessary software installed to connect to the Internet, then it will be loaded, the user may be prompted to login, and a connection to the Internet will be attempted.
Let's look at the AsyncRead method:

 AsyncRead(Target As String,
          AsyncType As AsyncTypeConstants
          [, PropertyName])
The AsyncRead method begins the download operation. The Target argument is the URL that points to the data to be downloaded. The AsyncType argument specifies the type of data to be downloaded. It can be one of the three values in the AsyncTypeConstants enumeration (see Figure 2). The optional Property argument defines the name by which this download operation will be known. Normally this is the property where you want the downloaded data to be stored. Note, however, that specifying a property name does not cause the data to be automatically assigned to the property. Instead, this simply allows a control to differentiate between what might be several different, asynchronous operations proceeding simultaneously. Whatever name is provided in the Property argument is later provided to the control in the AsyncReadCompleted event. Here is a sample AsyncRead call:

 AsyncRead "",
           vbAsyncTypeFile, "MyData"
Now, let's examine the AsyncReadComplete event:

 AsyncReadComplete(AsyncProp As AsyncProperty)
The AsyncReadComplete event notifies your program that an asynchronous download has completed. The AsyncProperty parameter is an object with three properties: AsyncType, PropertyName, and Value (see Figure 3). The first two properties are the same values passed to the AsyncRead method when the download began. This enables a control to determine which download has completed and the type of data returned. The Value parameter is a variant that contains the actual data downloaded. This is normally used to assign the data downloaded to a property of the control.
The Value parameter obviously depends on the type of data downloaded. If a picture was downloaded with the vbAsyncTypePicture data type, then the Value parameter will contain an object of the Picture type. This can be immediately assigned to any Picture property, displaying the downloaded file. If a file was downloaded, the Value property will contain a string indicating the complete path of the file on the local machine. Files are normally downloaded to the C:\Windows\Temp folder and given a temporary file name like ~DFA034.TMP. The control can now open the file and read its contents via the normal file-handling features of Visual Basic, such as Open, Input, Close, and so on. If the vbAsyncTypeByteArray was used in the AsyncRead call, then the data is placed in the Value parameter as a byte array. It is assumed that the control will know how to handle this data.
The CancelAsyncRead method cancels an asynchronous data download already in progress.

If a PropertyName argument is provided, then only the specified download is canceled. All other downloads continue normally. This method is often called in response to the user aborting a download.
So how do you actually use the asynchronous download feature of Visual Basic? Let's say you want to create a control that displays a GIF file downloaded from the Internet. Since it could take a long time, you should download it asynchronously. A weather-map control that always shows the latest satellite image is a good example.
This asynchronous download technique described here may be used for files on the local machine in addition to data on the Internet. One popular use of asynchronous download capabilities is progressive image rendering. That means that the image is displayed as it is downloaded, either bit-by-bit (don't take that too literally), or in low-detail followed by mid-detail and high-detail renderings. This works by having the system send notification events periodically during the download process versus only when the download is complete. This idea of progressive rendering can also be used for other types of data besides graphics. An application might simply use the notification events to display a progress bar, indicating to the user what percentage of the download is complete. When graphic data is not involved, the more general term progressive data retrieval is used. Although the Asynchronous Moniker Specification from Microsoft provides support for progressive data retrieval, Visual Basic currently does not.

The Hyperlink Object

Part of the ActiveX specification defines an area of functionality called ActiveX hyperlinking, which defines a model for how applications, documents, and controls interact during hyperlink navigation. The Web is known for its ease of use; the ActiveX hyperlinking specification is meant to offer a similar navigation model to your applications.
ActiveX hyperlinking works in hosts that implement the specification, such as Microsoft Internet Explorer and Visual Basic. For ActiveX controls running within Internet Explorer, hyperlinking offers the control full integration with the history list and URL-based navigation. In a container such as a Visual Basic form, the hyperlinking feature simply launches Internet Explorer to accomplish hyperlink navigation.
Visual Basic exposes the ActiveX hyperlinking capability via the UserControl.Hyperlink property, which provides a reference to a Hyperlink object. The Hyperlink object gives your control access to the ActiveX hyperlinking functionality. Using the properties and methods of the Hyperlink object (see Figure 4), your control can request a hyperlink-aware container, such as Microsoft Internet Explorer, to jump to a given URL or to navigate through the history list. If your control is not running in Internet Explorer, then the Hyperlink property may be 0. You should always check for this before using the Hyperlink reference. Visual Basic supports the Hyperlink object by simply calling Microsoft Internet Explorer via ActiveX automation interfaces.

A Sample Internet Control

The kind of control we'll implement here is one you might already have on your machine. In fact, if you use Microsoft Internet Explorer 3.0 as your Web browser, and have ever visited, then this control was automatically downloaded and installed on your computer. The control I am speaking of is the popup menu that appears when you press on the little down arrows at the top of the Web page. The popup menus allow you to navigate to different resources available on the ActiveX Web site. Let's duplicate the functionality of Microsoft's Internet menu control in Visual Basic.
First and foremost we need to define the control's interface. The interface that the control exposes to developers is very important to its success. If the control is difficult to work with or hard to learn, developers won't use it. In addition, once a control's interface has been defined and is being used in software projects, changing the interface will usually cause existing code to break.
To define the interface, we need to decide what properties, methods, and events will be exposed by this control. Let's walk through how the user will interact with the control, and how the control will respond.

  1. The user sees a small bitmap that asks to be clicked
  2. The user clicks on the bitmap, sending a click event to the control
  3. The control displays the popup menu
  4. The user makes a selection
  5. The control fires an event at its container, specifying which item was selected
This still lacks one piece. When the control goes to display the popup menu, how does it know what items to include in the menu? Clearly we need some mechanism to enable the container to tell the control ahead of time what items to display in the menu. We have basically two choices—a property or a method. A method is normally used to perform some action on a control, while a property is used to set a data attribute. What we want here, the ability to define the items in a menu, fits better into the model of a property. So let's define a property called MenuItem that the container will set to define the menu. Since there will usually be more than one menu item, we will need an array of MenuItems.
To better understand the interface, I find it helpful to imagine the code that the container might execute to program the control. On startup, a container would execute the following code to define the menu items.

 MyMenuControl1.MenuItem(1) = ""
 MyMenuControl1.MenuItem(2) = ""
 MyMenuControl1.MenuItem(3) = ""


Well, that pretty much rounds out the design of the control. Let's see how it is implemented. Obviously, we will use a property procedure for the MenuItem property. Creating a property procedure that pretends to be an array is a bit tricky. The Property Let procedure will take two arguments.The first argument of the Property Let procedure will be the index into the array, and the second will be the actual value, as shown here:

 Public Property Let MenuItem(ItemNumber As Integer,
                              Caption As String)
 If ItemNumber <> 1 Then
     Load mnuPopupItem(ItemNumber)
 End If
 mnuPopupItem(ItemNumber).Caption = Caption
 End Property
The code tests if the index number is one because it depends on a menu array, an array of items defined in Visual Basic's Menu Editor. For this control, I have used the Menu Editor to define a menu called mnuPopup that contains an mnuPopupItem. A menu is usually not defined for most controls, since a control does not have a menu bar. The only reason for a control to define a menu at all is the popup menu facility described here. mnuPopupItem is the first item in the menu array, defined by setting the item's Index property to one. If the index in this code is one, then the menu item already exists and the code simply sets the caption. Otherwise, the Load statement is used to create a new menu item in the array before setting the caption.
Although not required in this case, it is good design to have a Property Get procedure to go along with the Property Let procedure defined above. What makes this pair of property procedures interesting is that the data sent by the container is not saved by the control. Since the data is being stored by Visual Basic in the popup menu, the data can simply be retrieved from there.

 Public Property Get MenuItem(ItemNumber As Integer) As String
 MenuItem = mnuPopupItem(ItemNumber).Caption
 End Property
Now that the menu is defined, the control needs to display it when clicked. Responding to the classic UserControl_MouseDown event gives us a chance to do this:

 Private Sub UserControl_MouseDown(Button As Integer,
                                  Shift As Integer,
                                  X As Single,
                                  Y As Single)
 PopupMenu mnuPopup
 End Sub
Once the menu is displayed and the user makes a selection, the control will be notified by way of the mnuPopupItem_Click event procedure. At this point, the container of the control needs to be notified. Raising events is usually the best way to notify your container that something has happened to the control. While we could have been rude and defined a custom event named, say, ItemSelected, we chose instead to use the standard Click event. First, in the Declarations section of the control, we declared the event:

 Event Click(ItemNumber As Integer)
Then, in response to a selection from the popup menu, we raise the event, passing the Index number of the selected item as a parameter to the receiving event procedure.

 Private Sub
       Index As Integer)
    RaiseEvent Click(
 End Sub
At this point we have most of the pieces in place. The Click event procedure is raised in the container in response to a selection. What you do here is entirely up to you. In the Visual Basic form used for testing, we simply display the item that was selected from the popup menu.

 Private Sub
       ItemNumber As Integer)
    Print MyMenuControl1.MenuItem(
 End Sub
Although we used a Visual Basic form to test this control, a popup menu control for Visual Basic programmers would probably not have large appeal since Visual Basic already provides the very easy-to-use PopupMenu statement. However, used in a Web page, this control could help enable users to navigate the page in a simple manner.
To insert the control described above into a Web page, you first need to compile it as an OCX. Then you might use the ActiveX control Pad to insert it into a Web page, or you might enter the <OBJECT> tag directly into an HTML document as shown here:

 <OBJECT ID="MyMenuControl" WIDTH=100 HEIGHT=51
         <PARAM NAME="MenuItem(0)" value="">
         <PARAM NAME="MenuItem(1)" value="">
         <PARAM NAME="MenuItem(0)" value="">
Be sure to look up the CLSID number from the Windows registry and replace the dummy class identification number shown here. Then when the user has made a selection from the popup menu, you could intercept the event using VBScript code in the Web page:

 Sub MyMenuControl_Click(ItemNumber)
 Select Case ItemNumber
     Case 1
     Case 2
     Case 3
 End Select
 End Sub

ActiveX Documents: The Future of Forms

Visual Basic supports the creation of ActiveX documents via two special project types: ActiveX document DLL and ActiveX document EXE. ActiveX document forms, represented by the UserDocument object, can also be added to ActiveX code components such as ActiveX EXE and ActiveX DLL projects. In fact, an ActiveX document DLL is really an ActiveX DLL with a default UserDocument object instead of a default class module. The same is true of an ActiveX document EXE. ActiveX controls and standard EXEs do not support the UserDocument object. Just as with any other project type class modules, code modules, forms, and other Visual Basic constructs can be added to any ActiveX document projects.

Figure 5 ActiveX documents are like sophisticated form objects
Figure 5 ActiveX documents are like sophisticated form objects

Before we go any further, we should explain how ActiveX documents differ from ActiveX controls. While ActiveX controls are used as components to build other applications, ActiveX documents are the program. You don't, for example, put a bunch of ActiveX documents on a form, as you do with ActiveX controls. At runtime ActiveX documents are a combination of a user interface and data. The ActiveX document is the form, and you put ActiveX controls on it. ActiveX documents may have properties, but those properties won't show up in the Properties window. Also, there's not much point in having an ActiveX document fire an event. Who would respond to it? ActiveX documents are really more like sophisticated form objects (see Figure 5).

The UserDocument Object

ActiveX documents are supported in Visual Basic by a special UserDocument object, just as controls are supported by the UserControl object. The UserDocument object has a visual designer that looks identical to that of controls. You design and lay out your document using any desired control, just as you would design a standard Visual Basic form. You also set properties, call methods, and respond to events in standard Visual Basic fashion. UserDocument objects are saved in .DOB files by Visual Basic.
The UserDocument object also has several interesting properties, methods, and events. Like ActiveX controls, ActiveX documents support hyperlinking, asynchronous downloads, and persistent properties. The UserDocument object also has some unique properties, methods, and events intended specifically for ActiveX Documents and not supported by controls (see Figure 6).


We have just scratched the surface of the potential uses of Visual Basic 5.0. In addition to its native code generation and vastly improved user interface, developers can now use Visual Basic to write ActiveX controls, document objects, and Web applications. Properties, methods, and events work both in the classic Visual Basic context and in the new ActiveX context.

From the March 1997 issue of Microsoft Systems Journal. Get it at your local newsstand, or better yet, subscribe.

© 1997 Microsoft Corporation. All rights reserved. Legal Notices.

© 2016 Microsoft Corporation. All rights reserved. Contact Us |Terms of Use |Trademarks |Privacy & Cookies