Scripting Solutions with WSH and COM: Extending WSH with ActiveX Controls

Microsoft designed Windows Script Host (WSH) to use ActiveX controls that support automation. However, not all ActiveX controls work with WSH (e.g., the Task Scheduler API ActiveX control I discussed in "Advanced Methods for Task Scheduling," May 2002, InstantDoc ID 24592). A developer can wrap such an ActiveX control by using Visual Basic (VB) or another compiled language. In doing so, the developer creates a new automation ActiveX control that supports WSH, and the developer creates identical interfaces, methods, and properties (with all their associated parameters) in the new automation object. A WSH script can then call a method in the new automation object, and that object will call the identical method in the original nonautomation object and pass all parameters to the nonautomation object.

The developer must have the appropriate tools to wrap the original ActiveX control. Even then, this approach isn't always viable (e.g., the ActiveX control's contents might not be built for WSH scripting, preventing you from wrapping the ActiveX control). Fortunately, many automation ActiveX controls do work with WSH.

In the next few columns, I'll show you how to use several practical components from the Internet to extend WSH. To kick things off, I introduce you to an ActiveX control, Woodchop Software's GooeyScript, that lets you quickly create event-driven forms. I offer a brief overview of ActiveX controls, describe scripting with GooeyScript, then walk you through the process of scripting event-driven forms.

Understanding ActiveX Controls
Authors sometimes develop ActiveX controls that rely on VB runtime components. Usually, the controls call the methods or properties of core VB runtime DLLs. As a result, you must download and install these runtime components on each client PC on which you want to use the control. You can download the VB 6.0 runtime DLLs from http://www.microsoft.com/downloads/release.asp?releaseid=28337&area=search&ordinal=22 and download the VB 5.0 runtime DLLs from http://www.microsoft.com/downloads/release.asp?releaseid=12651&area=search&ordinal=9.

You must copy all ActiveX controls to the client PC that will use them and register them in the client PC's registry to make the controls available to your programs and scripts. To register ActiveX controls, you must call regsvr32.exe and specify the path to the control. For example,

regsvr32 /u /s c:windowssystem32mynew.dll

references the mynew.dll control. The /s switch silences the reference, and the /u switch indicates that you want to unregister the ActiveX control later, in case you want to remove references to the control from the registry.

Occasionally, the author of an ActiveX control will create an ActiveX executable (.exe file) rather than an ActiveX DLL because of the out-of-process threading model that ActiveX executables use. Whereas executables can spawn their own process, DLLs execute within the same process from which they're called. For example, GooeyScript is an out-of-process ActiveX executable: The script and the form run in separate processes, so the script executes while a form gathers or displays information. Although you can register an ActiveX executable with regsvr32.exe the same way you register a DLL, you would typically use the ActiveX executable's built-in registration capabilities (i.e., /regserver), as the following example shows:

GooeyScriptDemo.exe /regserver

Scripting with GooeyScript
Lee Carlson designed GooeyScript for WSH. You can download GooeyScript from http://www.woodchop.com. The demo version is full-featured except that it displays a splash screen for 10 seconds every time you open a new dialog box. To remove the splash screen, you must purchase the ActiveX control, at a cost of $1 per client (in blocks of 50 clients). However, I think this ActiveX control is worth the money.

Several Windows Scripting Solutions authors have offered better methods than Message Box and Input Box to create dialog boxes to use with WSH. Dino Esposito introduced an ActiveX control that he wrote to create dialog boxes. Several other authors and I have described how to use Microsoft Internet Explorer (IE) to create custom dialog boxes and progress bars. For a list of these articles, see "Related Articles in Previous Issues" on the Windows Scripting Solutions Web site (http://www.winscriptingsolutions.com, InstantDoc ID 25288). GooeyScript is a superbly customizable option.

GooeyScript lets you create versatile form dialog boxes (i.e., forms) that can include various form components (e.g., customized backgrounds, buttons, check boxes, combo boxes, progress bars, radio buttons) that full-blown applications require. In addition, GooeyScript lets you create forms that can pause a script to trap events that happen on the form and pass those events to the script.

When you download the GooeyScript .zip file, you must install the demo ActiveX control—gooeyscriptdemo.exe—and the VB 6.0 runtime DLLs on each client that will use GooeyScript before you begin scripting with this tool. GooeyScript comes with an excellent VBScript script that helps you use GooeyScript. In addition, the Woodchop Software Web site provides the full interface definition.

Creating Event-Driven Forms
For an overview of what you can do with GooeyScript, let's create some sample forms. I use Windows XP and Windows 2000 in the following examples, but the same principles apply to Windows Me and Windows 9x.

Creating a blank form. BlankFormWithProblems.vbs, which Listing 1 shows, uses the GooeyScript toolkit to create the simplest form of all. To begin, you use the WScript::CreateObject method to instantiate the GooeyScript::Form object for your first form, and you place that object into the gsForm variable. Next, you use the Form::Load method to set the properties for the newly created gsForm object. The Form::Load method includes eight parameters—in this case, you use only parameter 5 (to title the form) and parameter 8 (to indicate whether the form is visible). For information about the other parameters, review the documentation on the Woodchop Software Web site.

To make the form visible, you set the Form::Visible property to TRUE. You can eliminate this line and set the last parameter of Form::Load to TRUE. However, using the Form::Visible method becomes important when you add buttons and want everything to exist on the form before you make the form visible. Otherwise, the form will appear first, then the components will appear one at a time.

The script in Listing 1 places a blank form on screen. However, the blank form doesn't always appear in front of all the windows on screen. To ensure that this form will appear in front of all other windows, you must use the Form::Ontop property and add the following line to the form before you make the form visible:

gsForm.Ontop = TRUE

Unloading the form. The form that Listing 1 shows has a problem, as you might have deduced from its name. When you run the script, wscript.exe processes the script, gooeyscript.exe (or gooeyscriptdemo.exe) loads with the form, and wscript.exe stops running as the script ends. Although the script finishes, the form remains on screen. No problem, you just close the form and the process disappears, right? Wrong. The process doesn't go away. Instead, it just sits there using 3.6MB of RAM. You can use taskmgr.exe (or press Ctrl+Shift+Esc on the left side of your keyboard) to verify that the process is running. The process continues to run because you closed the form but didn't unallocate the form object from memory. In fact, if you could still access the form (you can't because the script has terminated and taken the gsForm variable with it), you could manipulate it. To fix the problem, you must add the Form::Unload method to the end of the script.

Some scripts have lines at the end to remove object references—for example,

Set gsForm = Nothing

You don't have to include such end lines with WSH because WSH declares variables and removes object references automatically. GooeyScript, however, requires that you use Form::Unload on all forms. Otherwise, every time you call a new script, you instantiate another copy of GooeyScript into memory that will disappear only when you log off or reboot.

Pausing the form. The form still has a problem that you need to resolve. Listing 2 shows WhereDidItGo.vbs, a modified version of Listing 1 that includes the additional lines I just discussed and the Form::Unload method call. If you run the script in Listing 2, the form appears and disappears so quickly that it's hard to see. WSH interprets the script at every line, and just because you instantiated a form and displayed it, the script doesn't know that you want to stop processing at this point—before the Form::Unload method call. You could use a WScript::Sleep method call to pause the script, but WScript::Sleep would make the form available only until the sleep period finished, then the form would unload.

Because you want the form to include buttons or options that users can select, you want the script to pause execution until the script retrieves the results of any choices the user made on the form. To pause the script execution, you need to move onto a slightly more complex script that will form the basis of any form creation you do with GooeyScript.

Creating a basic working form. Listing 3 shows BasicWorkingForm.vbs, which lets you create a single-button form. After the form appears on screen, the script pauses until the user clicks the form button. Then, the script continues to execute, the form unloads gracefully, and the script ends.

First, you need to instantiate the GooeyScript::Form object for your form just as before, using the WScript::CreateObject method and placing that object into the gsForm variable. This method call differs from the Listing 1 method call, however, because you need to extend the WScript::CreateObject method and use a second parameter. A key part of the Listing 3 method call is creating an event handler that can respond to events that the form fires at the event handler. To accommodate these events, you need to pass a second parameter to the script, which consists of a string of text characters ending in an underscore (_).

Set gsForm = _ WScript.CreateObject _("GooeyScript.Form", "gsForm_")

By trapping events, you can create subprocedures such as gsForm_ComboBoxClick and gsForm_ButtonClick to respond to GooeyScript events.

After you load the form, you can use the Button::Load method to add the button to the form as follows:

gsForm.Button.Load "ButtonExit", _175,75,180,125,"Exit the form", TRUE

This method creates a button (with the object name ButtonExit) that says Exit the form. The button, which is 180 pixels wide and 125 pixels high, appears 175 pixels from the left edge of the form and 75 pixels from the top. The last parameter makes the button visible when the form is on screen. When a user clicks the button, the script passes the object name to the event handler to identify which button the user clicked. Because this form has only one button, you don't have to worry about which button the user clicked. However, if the form had multiple buttons, identifying which button the user clicked would be crucial.

Next, you can make the form visible and use GooeyScript's Form::Pause method to halt execution of the script until an event calls the Form::UnPause method. At this point in the script, you define an event handler to trap the Form::ButtonClick event that GooeyScript sends. Although this event takes a parameter (i.e., the button name), you don't use it in the script. When a user clicks the button, the event handler simply calls the Form::UnPause method so that the main body of the script can continue to execute. The subprocedure that calls Form::UnPause is

Sub gsForm_ButtonClick _(strButtonName)gsForm.UnPauseEnd Sub

After the script calls the Form::Pause method, you insert the remaining commands (e.g., Form::Unload) that must execute to close the script and remove all instances of the GooeyScript form objects.

Expanding on GooeyScript
You now know how to use GooeyScript's basic features to easily create forms. In my next column, I'll describe how you can use GooeyScript to create other useful components such as custom backgrounds and progress bars and introduce you to another useful ActiveX control.