© Microsoft Corporation. All rights reserved.

December 2000

Getting Started

Extend your bag of VB programming tools with ActiveX controls. Create a simple but useful Hyperlink control you can reuse in your own projects.

by Stan Schultes

An ActiveX control is a packaged code component built for easy reuse within a container application such as VB, Microsoft's Office apps, or Visio. A container app is any program built on Microsoft's ActiveX standard that you can load software components into. The DBGrid, MSChart, and TreeView controls are all examples of common ActiveX controls.

Your ActiveX control runs in an environment the container provides. The control can share information with the container, though not all containers are the same. Some containers provide more or less functionality in their control-hosting environment, so your control must be able to deal with errors that might occur due to container differences. VB tends to be the standard by which other containers are measured because it offers a great deal of functionality.

The sample Hyperlink control (download the sample code) is a labeled hyperlink—that is, it consists of a hyperlink and an associated label. When you position the label relative to the hyperlink, the control resizes the label and hyperlink automatically as their relative positions change. The control formats the string in color to look like a hyperlink, with an optional underline if you put a valid URL into the hyperlink.

The control displays a hand-shaped mouse icon when you move the mouse over the hyperlink, similar to what happens when you pass the cursor over a hyperlink on a Web page. You can set two colors on the hyperlink: a default color and a second color once the user has clicked on the hyperlink. You raise an event from the control when the user launches the hyperlink successfully.

You have two choices when writing the code for your ActiveX control: Either use the ActiveX Control Interface Wizard or write your code by hand. It's best to start with the wizard, especially when you're building your first control, because it saves you time and reduces the tedium of creating template property, method, and event (PME) code.

Before starting the wizard, you must first create a new ActiveX control project and place all constituent controls on the default UserControl designer. You also must have a good idea of what your control does—that is, what the PMEs are. The wizard lets you rerun it to add, remove, or modify features as long as you don't change the comment lines the wizard inserts—a nice feature.

Create the ActiveX Control Project
To start the project, open VB and choose the ActiveX Control project type. Set the name of the UserControl that was created by default to HyperControl and the project name to Hyperlink. Add two Label controls to the default UserControl, name them lblHLLabel and lblHyperlink, and save the project. You can now run the wizard because the two labels are the only required constituent controls for Hyperlink to operate.

You can find the ActiveX Control Interface Wizard on the Add-Ins menu, but you might need to go into the Add-In Manager and load the wizard for it to appear. To keep Hyperlink simple, select the interface and custom members in the wizard and map the PMEs (see Table 1); be sure to enter descriptions for all custom PMEs you add. Use the wizard's defaults for the LabelPosition property and for the Launched event in the Set Attributes dialog.

	Figure 1 Test the Hyperlink Control. Click here.

After running the ActiveX wizard, fix up the property persistence functions in your control's code: InitProperties, ReadProperties, and WriteProperties. The wizard hardcodes property names and default settings, but because you use each value three times, you should use constants for both property names and default values to improve maintainability. You should also call the property procedures themselves to take advantage of input validation and customizations, instead of reading and writing values directly into the member variables.

Next, create a test harness for the Hyperlink control so you can test all its PMEs to ensure their correct operation. Create a project group by choosing the File menu's Add Project item and selecting the Standard EXE project type. Name the project HyperlinkTest, and rename Form1 to frmHyperTest. Right-click on the HyperlinkTest project item in the Project Explorer window and choose Set as Startup from the popup menu so frmHyperTest loads first when the project group is run. Then save the project group as HyperlinkGroup.

Now, go through each of your new ActiveX control's wizard-generated PME routines, add a test mechanism to frmHyperTest, and verify that each PME procedure operates correctly. You get the best results by approaching the process methodically and concentrating on one property or group of related properties at a time.

The LabelPosition property specifies the position of Hyperlink's label relative to the hyperlink field. By changing the LabelPosition from the default Variant to an Enum, you represent all its possible positions:

Public Enum HLLabelPosition
   hlHidden = 0
   hlAbove = 1
   hlBelow = 2
   hlLeft = 3
   hlRight = 4
End Enum

Using the Enum in LabelPosition Get and Let property procedures does two things for you (see Listing 1). First, VB's IntelliSense statement completion shows you the Enum values when you reference the LabelPosition property in code. Second, VB gives you the list of Enum values in the Properties window when you change the design-time properties of the Hyperlink control.

In the LabelPosition Property Let, call the PositionLabel routine to move the constituent controls within the Hyperlink control (see Listing A). Call the PropertyChanged function, which tells VB to update the value in the Properties window when the property value changes—the last step in any Property Let procedure.

Go Into Run Mode
The Hyperlink control has been in design mode up to this point. As the control's developer, you work in design mode to modify or add to your control's behavior. When you test your control, you put it into run mode, which is the mode users of your control work with as they develop their own apps. With Hyperlink's UserControl open (the HyperControl item in the Project Explorer window is highlighted), press Ctrl-F4 to close the UserControl and put Hyperlink into run mode.

You draw a Hyperlink control on frmHyperTest by clicking on the icon in the toolbox first, then clicking and dragging a rectangle on the empty form (see Figure 1 for the complete form). Next, add a Frame control to frmHyperTest and place five option buttons in a control array on the frame to represent the LabelPosition Enum values. Code the option button Click event to set Hyperlink's LabelPosition property, and check that the constituent controls are positioned correctly.

Now double-click on the HyperControl item in the Project Explorer window to put the Hyperlink control back into design mode. The instance of Hyperlink on frmHyperTest appears with a cross-hatch pattern on it to remind you the control is in design mode. Whenever you add code in Hyperlink's code window, the hatched control instance appears again on frmHyperTest to indicate you need to update it again to reflect your changes. You can then right-click on frmHyperTest and choose the Update UserControls item on the popup menu to refresh the Hyperlink instance on the form.

The OLE_COLOR Property datatype tells VB to display a color dialog in the Properties window when you set color values at design time. Use the OLE_COLOR datatype definition for the ForeColor, BackColor, HyperlinkColor, and HyperlinkClickedColor property procedures. The ForeColor property applies to the Hyperlink caption only; use HyperlinkColor and HyperlinkClickedColor properties for the Hyperlink's URL.

You need to set a special procedure ID so the caption and URL strings in Hyperlink update as you type strings in the Properties window. Place your cursor in the Caption property procedure, choose the Tools menu's Procedure Attributes item, then click on the Advanced button. Select the Caption item in the procedure ID drop-down box, then select the Text item in the procedure ID drop-down box for the URL property.

Declare the Font property procedures as type Font to tell VB to show the Font dialog box when you change Hyperlink's Font properties in design mode (see Listing 2). Use the Property Set procedure instead of the usual Let procedure because a variable declared as type Font is an object. You call the FormatHyperlink procedure within the Font Property Let procedure to set all the hyperlink's attributes (see Listing B).

Here's a neat trick to make the URL act like a browser hyperlink: Use the DragDrop routines to detect reliably when the user moves the cursor over or off the URL label (see Listing C). This allows you to display the hand icon while the cursor is over the URL, or to restore the normal cursor when it's not. The lblHyperlink_DragDrop event routine launches the hyperlink using the UserControl's Hyperlink.NavigateTo method when you click on the URL.

Deploying the control is the final step in developing the ActiveX control. Compile your control into an OCX file and build a setup kit, which is required if you want to use your ActiveX control on a machine that doesn't have VB installed. The Package and Deployment Wizard in VB can help you build and deploy a setup kit.

You now have an idea of the effort needed to build your own ActiveX control. Be sure you weigh the time required to build a control against the cost of buying one—unless you need unique functionality that you can't buy straight off the shelf. The ability to build ActiveX controls pushes your VB programming to a new level, and lets you reuse your code easily. Put your new ActiveX control in your toolbox and code on.

Stan Schultes is a project manager and VB and Web enterprise application developer in Sarasota, Fla. Stan is an MCP in VB and spoke on VB development at Microsoft's DevDays conference. He is a contributing editor for VBPJ and writes regularly for the magazine. Reach Stan at Stan@VBExpert.com.