[Previous] [Table of Contents] [Next]

Using the Popup Method

Unfortunately, JScript doesn't support the MsgBox function. Instead, you can use the Popup method provided by WSH. (You can also use the Popup method in VBScript instead of the MsgBox function.)

Because Popup is a method, it isn't part of the script language itself. It's part of the WSH object model and is exposed from the WshShell object, as you can see in Figure 6-9.

Figure 6-9 The WScript and WshShell objects in the WSH object model

To use the Popup method to create the same customized dialog boxes that we created earlier by using the MsgBox function, you can use the following statement:

object.Popup parameters

But how do you get the object in this statement? WScript doesn't provide the Popup method, and WSH doesn't expose a WshShell object automatically. You need an interim step to instantiate (create an instance of) the WshShell object and retrieve a reference to the object instance before you can use the Popup method.

You can instantiate an object in several ways. In WSH scripts, you can use the CreateObject method of the WScript object. CreateObject uses the ProgID of the requested object as a parameter. The WshShell object, which is a subobject of WScript, exposes the Popup method. The following statement creates a reference to the object in JScript:

var WshShell = WScript.CreateObject("WScript.Shell");

WScript is the object, and it supports the CreateObject method. This method requires one parameter containing the ProgID. For the WshShell object, this ProgID is defined as WScript.Shell. The CreateObject method searches the registry for the required object. If the object is already installed, an instance is loaded into memory and a reference to the instance is returned by the CreateObject method. This value is assigned to a variable (such as WshShell in the statement above).

The preceding statement creates a new object instance and stores a reference to it in the object variable. You can use this object variable to access the object's methods and properties. The following statements use the Popup method in JScript:

var WshShell = WScript.CreateObject("WScript.Shell");
var intDoIt;
intDoIt = WshShell.Popup(Message,
                         0,
                         Title,
                         vbOKCancel + vbInformation);

After creating the object variable WshShell, you can use WshShell.Popup to display the dialog box. The call to WshShell.Popup uses the following syntax:

res = WshShell.Popup(prompt, wait, title, buttons);

The Popup method has the following parameters:

After the dialog box is closed, Popup returns the code of the button that the user clicked to close the dialog box.

NOTE
The CreateObject method has an additional parameter, which I've skipped here, related to event handling. VBScript and JScript also have similar, built-in functions for creating objects. I'll go into more detail about CreateObject and the native object-creation functions in later chapters.

After creating the object variable WshShell using CreateObject, you can use WshShell.Popup to display the dialog box. But JScript doesn't use predefined symbolic constants (such as VBScript's vbOKOnly), so you have to combine the numbers given in Tables 6-1 through 6-4 to define the icon, buttons, and return value, as shown here:

var vbOKCancel = 1;
var vbOK = 1;
var vbInformation = 64;
var vbCancel = 2;

Using these variables as "pseudoconstants" improves the readability of your JScript script and simplifies porting between VBScript and JScript.

NOTE
The Popup method uses similar parameters and returns the same results as the MsgBox call. But the number of parameters and their order aren't the same.

Listing 6-7 is a JScript sample that uses the Popup method.

Listing 6-7 Popup.js

//************************************************
// File:    Popup.js (WSH sample in JScript) 
// Author:  (c) G. Born
//
// Using the Popup method to show a dialog box
//************************************************

// Declare variables.
var vbOKCancel = 1;
var vbOK = 1;
var vbInformation = 64;
var vbCancel = 2;
var result;

var Message = "Click a button";
var Title = "WSH Popup sample";

// Create the WshShell object variable.
var WshShell = WScript.CreateObject("WScript.Shell");

result = WshShell.Popup(
            Message,
            0,
            Title,
            vbOKCancel + vbInformation); // Show dialog box.

if (result == vbOK) // Check and show results.
{
    WScript.Echo ("OK button clicked " +
                  "(Code: " + result + ")");
}
else
{
    WScript.Echo ("Cancel button clicked " +
                  "(Code: " + result + ")");
}  

WScript.Echo("We are ready");

//*** End

The following statement uses the Popup method to create the dialog box:

result = WshShell.Popup(
            Message,
            0,
            Title,
            vbOKCancel + vbInformation); // Show dialog box.

The pseudoconstants vbOKCancel and vbInformation set the buttons value. After the dialog box is closed, the Popup method returns the code for the button that the user clicked.

This statement tests the value returned from Popup:

if (result == vbOK)

If the value stored in result equals vbOK, the Echo method displays a message saying that the OK button was clicked:

WScript.Echo("OK button clicked " + "(Code: " + result + ")");

If the value in result isn't equal to vbOK, the else block is executed and the Echo method displays a message saying that the Cancel button was clicked.

Using Popup in VBScript

Most Visual Basic programmers will probably use the MsgBox call in their VBScript code. But if you want to use the Popup method exposed by the WshShell object, you can take the approach shown in Listing 6-8. I kept the code simple to highlight the use of Popup.

Listing 6-8 Popup.vbs

'************************************************
' File:    Popup.vbs (WSH sample in VBScript) 
' Author:  (c) G. Born
'
' Creating a dialog box using the Popup method
'************************************************
Option Explicit

Dim result
Dim WshShell

' We need the WshShell object.
Set WshShell = WScript.CreateObject("WScript.Shell")  

' Use the Popup method.
result =  WshShell.Popup("Click a button", _
                         0, _
                         "WSH Popup sample", _
                         vbOKCancel + vbInformation)

WScript.Echo "Return value ", result

'*** End

Another JScript Example Using Popup

Let's look at another JScript example that uses the Popup method. We'll create a welcome dialog box (as shown in Figure 6-10) that shows a user name and the current date.

Figure 6-10 A welcome dialog box containing the current date

You can use Popup to create title text, and you can use the time-out value to close the dialog box after 10 seconds without any user interaction.

The following lines define two psuedoconstants containing the values for the buttons parameter in a Popup call:

var vbOKOnly = 0;              // OK button
var vbInformation = 64;        // Information icon

You can define an array in JScript using the following statement:

var cmonth = new Array("January", "February", "March",
            "April", "May", "June", "July", "August",
            "September", "October", "November", "December");

The variable cmonth is an object containing the array data. The new Array keyword creates an array and assigns the values in parentheses to the new object variable cmonth. Later, you can access the array values using an index:

WScript.Echo(cmonth[0]);

The following commands use JScript functions to retrieve the date and split the date value into day, month, and year:

var mydate = new Date();           // Create date variable.
var weekday = mydate.getDay();     // Retrieve day of the week.
var day = mydate.getDate();        // Day 
var month = mydate.getMonth();     // Month (start with 0)
var year = mydate.getYear();       // Year

Because a date must be stored in an object variable, the first line uses the new operator to create an object variable. The Date method returns a reference to a Date object, which is assigned to the variable mydate. The following line creates the message shown in the dialog box:

var text = "Today is " + cday[weekday]  + ", " 
        + cmonth[month] + " " + day + ", " + year + "\n" 
        + "Windows has been launched";

You use the values of the variables weekday and month as index values for the arrays. As a result, the day of the week and the month name are concatenated into a string, which is assigned to the text variable.

The following statement creates the dialog box containing the message.

objAdr.Popup(text, 10, title, vbOKOnly + vbInformation);

If the user doesn't close the dialog box within 10 seconds, Popup closes it automatically. You can see the details in Listing 6-9. (For more information on all the JScript functions, see the JScript Language Reference, which is available on the book's companion CD.)

Listing 6-9 Welcome.js

//************************************************
// File:    Welcome.js (WSH sample in JScript) 
// Author:  (c) G. Born
//
// Using Popup to create a welcome dialog box 
// containing the current date
//************************************************

// Define "constants" for Popup.
var vbOKOnly = 0;              // OK button
var vbInformation = 64;        // Information icon

// Create array variables for the message strings.
var cmonth = new Array("January", "February", "March",
            "April", "May", "June", "July", "August",
            "September", "October", "November", "December");

var cday = new Array("Sunday", "Monday", "Tuesday",
            "Wednesday", "Thursday", "Friday", "Saturday");

var name = "Born";              // Set user name.
var firstname = "G.";

// Create a welcome message.
var title = "Welcome, " + firstname + " " + name;

// Create object to use the Popup method.
var objAdr = WScript.CreateObject("WScript.Shell");

var mydate = new Date();           // Create date variable.
var weekday = mydate.getDay();     // Retrieve day of the week.
var day = mydate.getDate();        // Day 
var month = mydate.getMonth();     // Month (start with 0)
var year = mydate.getYear();       // Year

var text = "Today is " + cday[weekday]  + ", " 
        + cmonth[month] + " " + day + ", " + year + "\n" 
        + "Windows has been launched";

// Create the dialog box using Popup; define 10-second time-out.
objAdr.Popup(text, 10, title, vbOKOnly + vbInformation);

//*** End

NOTE
To show the welcome message in the Welcome.js sample, follow the directions given earlier for copying Welcome.vbs to your Startup folder.