Scripting Solutions with WSH and COM: Using WSC to Build a Progress Bar Dialog Box, Part 4

This column is the last installment in a four-part series about how to use Windows Script Components (WSC) to create a progress bar dialog box that you can use with your scripts. Previously, I discussed the various XML elements in a .wsc file ("Scripting Solutions with WSH and COM: Using WSC to Build a Progress Bar Dialog Box, Part 1," September 2000), how to use those elements to create a ProgressDialogBox object and its methods and properties ("Scripting Solutions with WSH and COM: Using WSC to Build a Progress Bar Dialog Box, Part 2," October 2000), and how to create an HTML template that the .wsc file uses ("Scripting Solutions with WSH and COM: Using WSC to Build a Progress Bar Dialog Box, Part 3," January 2001). I finish this series by describing the seven functions in the .wsc file. These functions define the ProgressDialogBox object's methods (i.e., Open and Close), properties (i.e., Visible, Line1, Line2, and PercentComplete), and event (i.e., Cancel). I also describe how to register the progress bar component and call it into action in a script.

Understanding the Open Function
The Open function, which Listing 1 shows, defines the ProgressDialogBox object's Open method. As callout A in Listing 1 shows, the Open method has six parameters:

(In Part 1 and Part 2, I mentioned that the Open method had five parameters. At that point, I didn't include the parameter for the HTML template created in Part 3.)

The Open function uses VBScript's CreateObject function to create a copy, or instance, of Microsoft Internet Explorer's (IE's) Application object and assigns that instance to the objIE variable. The function then sets the intTop, intLeft, intHeight, and intWidth variables to the values you pass in with the calling script. Next, the function sets IE's MenuBar, ToolBar, and StatusBar properties to False so that you'll receive a browser window with no menu, tool, or status bars.

Next, the Open function uses IE's Navigate method to load the HTML template into the IE browser. Loading a page can take a few seconds, so the function continually checks IE's Busy property for a Boolean value of True or False in a While...Wend loop. When the Busy property returns False, it means that IE has finished loading the template, and the loop ends.

Finally, the Open function sets four values within the HTML template. Remember from last month's column that ProgressBarTitle, ProgressBarLine1, ProgressBarLine2, and ProgressBar are unique IDs representing the dialog box's title, two progress statements, and progress bar, respectively. As callout B in Listing 1 shows, the function uses the WebBrowser object model's innerTEXT method to set the ProgressBarTitle, ProgressBarLine1, and ProgressBarLine2 values and Value property to set the ProgressBar value. Specifically, the function is setting ProgressBarTitle to the title you pass in with the calling script (i.e., strTitle) and setting ProgressBarLine1, ProgressBarLine2, and ProgressBar to empty strings to initialize those values. (For a general description of the WebBrowser object model, see http://msdn.microsoft.com/library/techart/msdn_lassesen.htm. For detailed information about this model's objects and collections, see http://msdn.microsoft.com/workshop/c-frame.htm?/workshop/author/dhtml/reference/objects.asp. For detailed information about this model's properties, see http://msdn.microsoft.com/workshop/c-frame.htm?/workshop/author/dhtml/reference/properties.asp.)

Understanding the Other Functions
The rest of the functions in the .wsc file—the Close, Visible, put_Line1, put_Line2, and put_PercentComplete functions—are much simpler. The Close function defines the ProgressDialogBox object's Close method. This function uses IE's Quit method to quit the IE session, which in turn, closes the progress bar window.

The Visible function defines the ProgressDialogBox object's Visible property. This function lets you show or hide the progress bar window. To show the window, you pass in a value of True to IE's Visible method. To hide the window, you pass in a value of False.

The put_Line1 and put_Line2 functions define the ProgressDialogBox object's Line1 and Line2 properties. The functions use the innerTEXT method to modify the text in the progress statements (i.e., ProgressBarLine1 and ProgressBarLine2).

The most-used function in the .wsc file is put_PercentComplete. This function, which Listing 2 shows, defines the ProgressDialogBox object's PercentComplete property. The put_PercentComplete function takes an integer percentage value between 0 and 100 and converts the value into a number of square blocks that fill up the progress bar. As I stated last month, the block character (*) is the letter n in the Wingdings font. The put_PercentComplete function defines that character as a constant. When a script's execution is 100 percent complete, the progress bar displays 33 blocks. To determine how many blocks to use for other percentages, the function uses VBScript's division (/) operator to divide the percentage value by 3, then uses VBScript's String function to construct a string of that many blocks. The function uses the Value property to set that string as the ProgressBar value.

When the put_PercentComplete function updates the blocks, it also checks to see whether the user has clicked Cancel, as callout A in Listing 2 shows. If a user clicks Cancel, the function uses VBScript's FireEvent method to fire off an event called Cancel.

Registering the Component
You can find the completed progress bar component, ProgressDialogBox.wsc, in the Code Library on the Windows Scripting Solutions Web site (http://www.winscriptingsolutions.com). Because the component's HTML template is a separate .htm file, the Code Library also includes the progress.htm file. You need to copy this file onto each machine you plan to run the .wsc file or reference the .htm file on a network share. To use the .wsc and .htm files, you need Windows Script Host (WSH) 2.0, VBScript 5.0, and IE 4.0 or later.

Before you can use the component, you must install and register it on every machine on which you plan to use it. First, copy the .wsc file on each machine. To manually register the component, right-click the ProgressDialogBox.wsc icon and select Register from the pop-up menu. (If you're debugging a component you've created, you must register the component before you can test it. After you make your changes, right-click the .wsc icon and click Unregister. Then, right-click the .wsc icon again and click Register.)

Because .wsc and .dll files are similar, you can use regsvr32.exe to automate the registration process. At the command line, type

regsvr32   "pathnameProgressDialogBox.wsc"

where pathname is the path to the file. Although regsvr32.exe automates the registration process, you must still individually register the component on each machine.

Using the Component
To use the progress bar component, you need a calling script. Listing 3 contains a demo script called WSHProgDialogDemo.vbs. As the demo script shows, you need to use the WScript object's CreateObject method to instantiate an instance of the ProgressDialogBox object. The CreateObject method's optional second parameter specifies the name of the event handler that the component will use if the Cancel event fires. (More on this event handler shortly.)

Next, you specify how you want the dialog box to look initially. The code at callout A in Listing 3 shows this code. You use the ProgressDialogBox object's Open method to specify the HTML template to use and the dialog box's title and four positional parameters. You use the ProgressDialogBox object's Line1 and Line2 properties to specify the two lines of text (i.e., ProgressBarLine1 and ProgressBarLine2, respectively) that the dialog box will initially display. Finally, you use the ProgressDialogBox object's Visible property to make the dialog box visible.

The demo script uses the WScript object's Sleep method to wait 150 milliseconds (ms) before updating ProgressBarLine1, ProgressBarLine2, and ProgressBar. Without these pauses, the demo script would execute so fast (because it's so short) that your eyes couldn't follow the progress in the dialog box. (To see what I mean, remove the WScript.Sleep lines from this script, then run it.) In an actual script, you don't need to include these pauses. (If a script executes so fast that you need pauses to view the progress in the dialog box, you don't need to use this dialog box to monitor the script's progress.)

The code at callout B in Listing 3 uses a counter to constantly update ProgressBar and ProgressBarLine2. The count starts at 1 and goes to 100 in increments of 1, with a 150ms pause between each count. In your script, your code to perform certain tasks would replace all the code that callout B highlights. Throughout your code, you need to insert the ProgressDialogBox object's PercentComplete property to provide a value specifying the progress that's occurred up to that point. You need to insert the PercentComplete property often because it not only updates the script's progress but also checks for a Cancel event. The code after callout B writes the final two lines in the dialog box, pauses for a while, then closes the IE window, which terminates the script.

The subprocedure at callout C in Listing 3 is a custom event handler called myEventHandler_Cancel(). The prefix myEventHandler_ represents the subprocedure that executes after the specified event (in this case, Cancel) has fired. So, if I had a second event called Moose, the subprocedure to execute after the Moose event has fired would be called myEventHandler_Moose.

The myEventHandler_Cancel() event handler changes the ProgressBarLine1 and ProgressBarLine2 lines to let the user know the box is canceling. The event handler then pauses, closes the IE window, and forces the script to quit. The last action is important because you want the script to stop executing. In your script, you can even add code to the event handler that reverses whatever changes the script has made up to that point.

Have Some Fun
In this series, I covered the WSC basics and showed you how to use WSC to create a progress bar dialog box for your scripts. As I mentioned previously, you can download all the code from the Windows Scripting Solutions Web site. So, download the code, try the demo script, then have some fun using the dialog box with your scripts.