Chapter 12

Distributing Your Control

• Compiling Your Control
  • Demonstration
  • Confirming That It Worked
• Binary Compatibility
• Naming Your Control
• Project Properties
  • Version Number
  • Version Information
  • Checking Version Information
  • Application
  • DLL Base Address
• Testing Your Compiled Control in Microsoft Access
• Using the Setup Wizard
• Binary Licensing
  • When to License
• Localization
• Registering and Unregistering Controls
• Using Regclean
  • A Word of Caution about Regclean
• Summary

By this time, you've been exposed to most of the functionality of a typical control. Now it's time to kick your control out of the nest and unleash it on the real world.

Getting an ActiveX control to end users isn't as easy as it was in the old days. In the 16-bit world of VBXs, you could distribute a VBX to a user simply by putting a copy of it into their \windows\system directory.

Not so with ActiveX controls. ActiveX controls must be registered with the system in order to work properly. You can register controls manually (using a registration utility called regsvr32), but in all likelihood you'll want to distribute your control to users without forcing them to register the controls manually. A Setup application does this for you; you can create a Setup application with the Visual Basic Setup Wizard.

Compiling Your Control

To get your control to users, you must first compile it. Compiling the control takes all of its code and other components and combines it into a .OCX file that you can distribute to users.

Demonstration

As a demonstration of how to compile and distribute your control, you'll compile a version of the HappyHour control you set up in a previous chapter. To compile this project, do the following:

1. Open the enhanced version of the HappyHour project on the CD-ROM that accompanies this book. Use the version in the Chapter 12 folder on the CD­ROM.
2. Select the menu command File, Make HappyHourProject.ocx.

3. The Make Project dialog box will appear. Confirm that the name of the .OCX file you want is correct.

4. Click on OK. The control will compile.

Confirming That It Worked

You'll be able to tell that your control is compiled because it will appear on the list of insertable controls in applications that support ActiveX controls. To see this list in Visual Basic 5.0, you use the Project, Components menu command. In Microsoft Access 95, you can see the list by opening a form in design view, then choosing the menu command Insert, Custom Control.

Binary Compatibility

When you compile your control, it is assigned a Globally Unique Identifier (GUID). A GUID is a 16-byte number that uniquely identifies your control to Windows. When your control is installed and registered on another user's system, the GUID is copied to that system's registry as part of the installation process.

Each time you compile your control, the random GUID generated by Visual Basic will be different, unless you have an option known as binary compatibility turned on. Turning on binary compatibility means that you're almost ready to distribute your control (or you've already distributed a version of your control) and you want to make sure that the version you're about to build remains consistent with future versions. (A side effect of turning this option on is that the GUID remains stable from one build of your control to the next.)

When you turn binary compatibility on, you're making a formal commitment to your control's interface. You can add new elements to your control's set of properties, methods, and events, but if you remove any part of the existing interface, backward compatibility with earlier versions of your control will break. Visual Basic will issue a warning to you when this happens.

To activate binary compatibility, do the following:

1. From the menu, choose Project, <my control name> Properties.
2. The Project Properties dialog box appears. Choose the Component tab. The dialog box should look like Figure 12.1.
   Figure 12.1 : The Component tab of the Project Properties window WordPad's Save As dialog box with the Text option enabled.

3. Click on Binary Compatibility, then click OK.

Naming Your Control

The name you give your control project and your UserControl designer determines the name the user will see when he places the control into a project.

Consider the SoundButton control as illustrated in Figure 12.2.

Figure 12.2 : SoundButton project names.

When a user of your control inserts it into his project, the control will appear in the list of available controls as SoundButton. (However, in Microsoft Access 95, it will appear as MySoundButton.SoundButton; see the topic "Testing Your Compiled Control In Microsoft Access" later in this chapter for more information.)

The moral of the story is that you should give your control project and UserControl a name that is going to make sense when a user browses the list of insertable controls.

Project Properties

You can assign a number of properties to your control project. These properties are added to the .OCX file at compile time.

Some project properties can be viewed by users of your control whether or not the control is actually installed on their machine. Such information is nice to add, because it makes it easier for users to manage .OCX files. If you don't add version information, for example, your users will have a hard time figuring out what your .OCX file does or where it came from.

To set project properties for your control project, select the menu command Project, <my project> Properties. Then choose the Make tab.

The Project Properties dialog box is shown in Figure 12.3.

Figure 12.3 : The Project Properties window.

The following are some details on what each of the project properties do.

Version Number

The version number of your control is important in situations where a user is re-installing or upgrading the control on a particular system. Most Setup programs will refuse to overwrite an existing copy of a control if the existing control is of a later version than the one it's trying to install. (That is, the Setup program won't kill version 2.0 of your control in order to install version 1.0.)

For this reason, it's important that you keep the interface of your control consistent across versions. (And by interface, I'm referring here to its programmable interface-its properties, methods, and events.) If you don't do this, newer versions of your control will break applications built on earlier versions. Once you've implemented an element of your programmable interface, it should stay there forever, even if you've since come up with a much better way to implement something.

To enable version numbering in your control, do the following:

1. In the Project Properties dialog box, select the Make tab.
2. If you want the revision number of your control to be automatically incremented each time it is recompiled, activate the Auto Increment checkbox. Otherwise, you will need to remember to change the version number manually each time you recompile your project (which is perfectly fine, if that's the way you want to go about it).

Version Information

Version information enables you to add some textual information to your control. Even if the control is not installed, the user can use the Properties page in Windows Explorer to figure out what your control is and where it came from.

The version information categories that you can include with your control are:

• Comments
• Company Name
• File Description
• Legal Copyright
• Legal Trademarks
• Product Name

It's particularly important to supply version information in the Company Name category, because guess which company's name appears in that slot if you don't include your company's name? (I'll give you a hint: It's two words, and it begins with the word "Microsoft" and ends with the word "Corporation.")

To supply version information with your control:

1. In the Project Properties dialog box, click on the type of version information you wish to supply.
2. In the Value box, type the value to be assigned to the category of version information. For example, Figure 12.4 shows a comment assigned to the Comments category of the SoundButton control.
   Figure 12.4 : Version information comments.

3. Continue to enter version information values for as many of the categories as you wish. When you're done, click on OK. You will, of course, need to recompile your control for the information to be included in the distributable .OCX file.

Checking Version Information

After you've compiled your control, you can inspect the version information compiled in with your control by doing the following:

1. Using Windows Explorer, locate your compiled .OCX file on disk.
2. Right-click on the file. The file's context menu pops up. Select Properties.
3. The control's Properties dialog box appears. Select the Version tab.
4. The control's version information is displayed, as illustrated in Figure 12.5.

Figure 12.5 : Version information in Windows Explorer.

Application

The Application panel determines two properties of your compiled application: its name and its icon. However, these properties do not pertain to ActiveX controls; they are used for compiled EXE projects only.

DLL Base Address

The DLL base address is the part of memory that your control loads into by default. (The reason why it's called the DLL base address and not the ActiveX base address is because ActiveX controls are really just another type of DLL.)

It's important to choose a DLL base address for your control because if you don't, the DLL base address for your control will be the same as the controls created by the millions of yo-yos out there who didn't buy this book and read this chapter. When your control is loaded into memory on a system that already has a DLL in memory at its base location, the operating system has to find a new slot in memory in which to load your control. This makes your control load more slowly, although how much more slowly is anyone's guess. (My guess is, since we're talking about a memory operation here, not that much more slowly.)

The key to solving this problem is to pick a base address that is different from the default. Valid DLL base addresses are multiples of 65,536 that fall between the range 65,536 and 2,147,418,112.

One handy way to come up with a DLL base address for your control is to pick a random number between two and 32,000-ish, multiply that number by 65,536, and use that as your base address. For example, I set the DLL base address of the SoundButton control project to 1179648 decimal (&H120000 hex), which is 65,536 times 18.

Using this method, you might run into a base address used by some other control, but it's not terribly likely. And even if you do, it won't cause a fatal error, just a teensy performance degradation at runtime.

You can access the DLL base address setting in the Compile tab of the Project Properties dialog box, as illustrated in Figure 12.6.

Figure 12.6 : Compile tab of the Project Properties dialog box.

Testing Your Compiled Control in Microsoft Access

Using Visual Basic to test your control is like driving a four-wheel-drive vehicle on the freeway on a sunny day. You might be able to verify that it works, but you won't have an idea of how it's going to perform in unexpected situations.

Testing your compiled control in a non-VB container such as this is like coating that sunny highway with a thin layer of tapioca pudding. Just as driving your Jeep down a pudding-covered highway gives you a sense of how it really handles, putting your control into a container other than VB, such as Microsoft Access 95, can give you important insights into how your control is going to behave in the real world.

Even if your control is destined for use in only one container (such as a Visual Basic project or a Web page) I'd recommend you test it in at least one other container, for no other reason than to gain a non-VB perspective on how your control will be used.

In this section, I'll demonstrate how a Microsoft Access user might use your compiled SoundButton control in an Access form.

To embed the SoundButton control in a Microsoft Access form, do the following:

1. Start Microsoft Access. You can either create a new database, use an existing database of your own, or use the example database provided on the CD-ROM that accompanies this book. The name of this database used in this example is example.mdb.
2. If you're using your own database or a new database, select the menu command Insert Form. The New Form dialog box appears (see Figure 12.7); select Design View, then click on OK. Or, if you're using the example database on the CD-ROM, locate the form called frmAddress in the database window, then click on Design. The form will appear in design mode.
   Figure 12.7 : Create New Form dialog box.

3. To insert the control onto the form, select the menu command Insert, Custom Control. The Insert OLE Custom Controls dialog box appears (see Figure 12.8). Scroll down until you find the SoundButton control, which appears in the list as MySoundButton.SoundButton.

Figure 12.8 : Insert OLE Custom Controls dialog box.

4. Click on OK. The button appears on the form. To confirm that it works properly, put the form into run mode by selecting the menu command View, Form.
5. The form goes into run mode (see Figure 12.9). Click on the SoundButton. It should generate the soothing click sound you've come to appreciate.

Figure 12.9 : Access form in run mode.

Using the Setup Wizard

If you're going to give your control to developers who are going to use it in Visual Basic or other development environments, you need to build a Setup application. The Setup application installs your control and, optionally, any attendant controls that are installed along with your controls, such as DLLs, constituent controls, help files, README files, and so forth.

To use the Setup Wizard to create a setup program for your control, do the following:

1. If Visual Basic is open, close it.
2. From the Windows taskbar, select the Visual Basic 5.0 program group.
3. In the VB 5 program group, choose Application Setup Wizard. This is illustrated in Figure 12.10.
   Figure 12.10: Launching the Application Setup Wizard.

4. The Setup Wizard runs and displays an introductory screen. Click on Next.
5. The Select Project and Options screen appears. Choose the project file for your control by browsing the disk and selecting the .VBP file.
6. If your control needs to be rebuilt (that is, recompiled), then make sure the Rebuild the Project checkbox is selected.
7. Finally, if you want the Setup Wizard to create a dependency file rather than a Setup program, make sure the Generate Dependency File Only button is selected. (A dependency file is a file that lists all the files that need to be distributed to users in order for your project to function.) The screen should look like Figure 12.11.
   Figure 12.11: The Select Project and Options window.

8. Click on Next. There will be a short delay while the Setup Wizard contemplates its navel. After a few seconds, the Distribution Method screen appears, as illustrated in Figure 12.12. Choose the option you want.

Figure 12.12: The Distribution Method screen.

9. Click on Next.
10. If you chose the Disk Directories option, you're next confronted with the Multiple Directories screen. Choose the directory into which you'd like your Setup program installed, then click on Next. If the directory you denote doesn't exist, the Setup Wizard will create it; however, if the directory you choose already contains files, the Setup Wizard will not delete those files for you. (For this reason, you should create a new directory or choose a directory you know is empty.) The screen should look like Figure 12.13.
    Figure 12.13: Setup Wizard's Multiple Directories screen.

11. The ActiveX Components screen appears. In this screen, the Wizard determines whether your project uses any constituent controls. If you wish to add constituent controls to your Setup program, you can do so now by clicking on Browse. Otherwise, click on Next.
12. The Confirm Dependencies screen appears. This screen informs you of the files required for your project to run. If you want more information on any of these files, click on File Details. Otherwise, click on Next.
13. The Setup Wizard enters an additional period of contemplation, during which you may wish to go out to the kitchen and obtain yourself a tasty beverage.
14. For an ActiveX control project, you'll get the message pictured in Figure 12.14. Of course you wish to include the Property Page DLL, because if you don't, your users will have a tough time gaining access to properties of your control at runtime. So if you plan on using your control in non-VB applications, click on Yes.
    Figure 12.14: Setup Wizard Property Page DLL message.

15. The File Summary screen (Figure 12.15) appears, showing a list of files that will be distributed along with your control project. If you need to add additional files to your installation (such as a readme file or a help file), now's the time to do it. Click on Add to add files.
    Figure 12.15: The File Summary screen.

16. Click on Next. The Setup Wizard is finished, so click on Finish. The Setup wizard dutifully collects and compresses files as you continue to enjoy your tasty beverage.

When it's all done, you've got a lovely Setup application on your disk, along with a couple of disks' worth of compressed support files.

Many (if not all) of these files do not actually need to be installed on your users' machines with each control you distribute. This is because most of these files are shared components that get installed into the user's Windows system directory. If your users already have a copy of the files you're distributing, the Setup program is smart enough to know not to litter their hard drives with additional copies. So if you're worried about dumping megabytes of junk on your users' disks, don't be.

Binary Licensing

Controls that support licensing enable you to restrict the use of your control. When your control is licensed, programmers are permitted to write code to access the interface of your controls within a development environment (such as Visual Basic's), and they can distribute the control to their end users. But those end users cannot access the control in a development environment unless they, too, have a licensed copy of the control.

Usually it's necessary to install a control (using the setup diskettes created by the developer of the control) to license the control. In the past, Visual Basic controls used tiny binary files stored in the Windows system directory as license files. ActiveX controls use registry entries for this purpose. Neither scheme will prevent a dedicated software pirate from making unauthorized copies of your controls, but adding support for licensing will slow down less technical (and less dedicated) users.

Controls that are destined for commercial distribution should always support licensing. You can add support for licensing to your control by doing the following:

1. In your control project, select the Project, <your project name> Properties menu.
2. In the Project Properties dialog box, select the General tab.
3. Select the Require License Key checkbox. The dialog box will look like Figure 12.16.

Figure 12.16: Requiring a license key.

If you have compiled your control already, you'll need to compile it again in order for the licensing requirement to take effect. Once you have done this, your users will have to install your control using a setup application you provide for them; simply placing a copy of the .OCX file on their system will not suffice.

When to License

It's a bad idea to require licensing when you're creating a control that you don't plan to sell. For example, if you wrote a control that acted as the interface for an expense account tracking system for your company, adding licensing support would be pointless; nobody (except a certifiable weirdo) would attempt to surreptitiously copy your control without your authorization. Also consider that, in this scenario, licensing adds an additional set of steps for your user. Instead of simply asking your network system administrator to blast a copy of your .OCX onto every computer on your LAN, you'd have to ask each user to install your control using a setup program you'd have to author.

Localization

A localized application is an application that has the ability to display text in different languages. Localization requires first and foremost a top-down planning effort. It is much easier to implement as you're building your application rather than after the fact (believe me).

The national language used by a piece of software is referred to as its locale. The locale of an ActiveX control is embedded into it by Visual Basic at compile time; if you're using the U.S. English version of VB, for example, your controls will have the U.S. English Locale ID.

You can determine the locale of the program in which your control is being used by inspecting the LocaleID property of the Ambient object. This property tells a localized control which language to display text in. If your control displays different text based on the LocaleID of its container, you should inspect the LocaleID in the InitProperties and AmbientChanged events of the UserControl.

Registering and Unregistering Controls

You may run into a situation of having to register your control manually without running a setup application. For example, if you compile a control, then move the control to another folder on your computer (to reflect the fact that the control has moved from development to production, for example), you need to re-register the control so that your system knows where to find the relocated .OCX file.

You can manually register a control using a utility called Regsvr32. For example, to register the SoundButton OCX manually, do the following:

1. Locate the utility regsvr32.exe on your disk. On my Windows NT machine, it's located in \windows\system32. The utility regsvr32.exe is installed by a number of applications, including Visual Basic and Microsoft Internet Explorer.
2. Using the Start menu in the Windows task bar, select Run. Enter the following command line:

c:\windows\system32\regsvr32.exe c:\windows\system32\sndbtn.ocx

3. The confirmation dialog box shown in Figure 12.17 is displayed.

Figure 12.17: Regsvr32 Successful.

You may find it useful to unregister a control, particularly in situations where you mistakenly registered a control or you simply want to clear a few controls off your system.

You can manually unregister a control by using the Start menu in the Windows task bar to select Run. Then enter the following command line:

c:\windows\system32\regsvr32.exe /u c:\windows\system32\sndbtn.ocx

Using Regclean

Regclean is a utility that checks your OLE registry and insures that all of the registered files actually exist on your computer. If it doesn't find the file that corresponds to the registry entry, it blows the registry entry away. This can be a great help when you're testing the ActiveX control registry. It's also nice to get rid of applications you installed years ago but have long since deleted. (Did I ever have Lotus Approach installed on my system? Yeees.) The latest version of Regclean is available on the Microsoft Web site at http://www.microsoft.com/kb/softlib/mslfiles/REGCLN.EXE. (An older version shipped with Visual Basic 4.0; I would imagine they'll ship it with VB5 as well.)

A nice thing about the way that Regclean works is that it leaves an undo file that tells you exactly what registry entries it removed. This file, undo.reg, is created in the same folder in which Regclean resides.

A Word of Caution about Regclean

I recently used Regclean on my Windows NT 4.0 machine. It came up with so many things wrong with my registry I permitted it to clean up all the problems it found without notifying me of what it was doing. It wound up hosing the registry of the Data Access Object (DAO) library used by Microsoft Access 95. It wasn't hard to fix-I just had to figure out which library it had un-registered, which took a few minutes, and then re-register it using the registration utility Regtlb32. I could have also simply re-installed Access 95. Not a huge deal, but do bear in mind that over-zealous use of Regclean can cause these kinds of problems.

Summary

This chapter discussed some of the more common methods of distributing controls to users. In addition to compiling the control into an .OCX and applying compiler-related properties to your control, the chapter covered a number of ancillary topics such as localization, the system registry, and licensing support.

The next chapter addresses a new way to distribute your controls to users-through a World Wide Web page.