Window Object Methods

Article
06/30/2006

The last major portion of the Window object’s programmability is embodied in its methods. The methods allow us to tell the browser to do a certain job, or perform some task that it knows how to accomplish.

The Window's Dialogs

The Window object contains three methods that display basic dialogs. We’ve already seen the Alert dialog in our examples. It’s about the simplest dialog we could experience—it just displays one text string and an OK button, but it’s exactly what we need in a lot of cases.

The other two dialog methods are Prompt and Confirm. The Confirm method displays a message box with the string specified in the method call, but instead of providing an OK button, it displays both OK and Cancel buttons, allowing the user to choose to confirm or abort an action. The method returns True value if the user presses OK, or False if the user presses Cancel.

Prompt is another way to request user input. This method displays yet another message box, with whatever string is passed as a parameter, but this time instead of OK or Cancel buttons, it displays a text box allowing the user to enter an arbitrary string. The code below uses all three of these methods, and shows the correct calling syntax for each method:

  <HTML>
<HEAD>
<TITLE> Window Dialogs </TITLE>
</HEAD>
<BODY>
<CENTER>
<H1> Window Dialogs </H1>
<INPUT TYPE="BUTTON" NAME="btnTest" VALUE="Click Me">
<SCRIPT LANGUAGE="VBScript">
Sub btnTest_onClick
Dim retValue
retValue = Confirm("Press OK or Cancel")
Alert "Confirm returned " & retValue
retValue = Prompt("Enter a string", "Default String")
Alert "Confirm returned '" & retValue & "'"
End Sub    
</SCRIPT>
</CENTER>
</BODY>
</HTML>

Pressing the single button on the page brings about a series of dialog boxes, first a Confirm dialog, then an Alert displaying the results of the previous Confirm. After these two dialogs, a Prompt dialog is displayed, and another Alert then shows the result. The second parameter to the Prompt method is the default string that will be displayed in the user entry text box.

If we’re using VBScript, we can get increased functionality with the MsgBox and InputBox statements and functions. Some languages, like JavaScript, don’t have built in dialog functions like VBScript does, and so these functions of the Window object can come in handy.

The Open Method

As is fitting for the object representing the browser window itself, the Window object provides methods to open new browser windows, close a window, and navigate to a new location. We’ll cover the Open method first.

Open is a simple method with many options that increase its complexity. In its simplest form, it just creates a new browser window, pointing to a given URL. For example, the following code creates a window named myWindow, which displays the Wrox Web page:

  Window.Open "http://www.wrox.com", "myWindow"

The complexity comes from Open’s optional third parameter, which we’re not using in this line of code. The extra parameter provides a fine level of control over the way the new window is displayed.

The following aspects of the window can be controlled by specifying values in the third parameter of our call to the Open method.

Parameter Text	Variable Type	Function
`toolbar`	boolean	display a toolbar
`location`	boolean	display the location text box
`directories`	boolean	display the special link buttons
`status`	boolean	display a status bar
`menubar`	boolean	display the menus at the top of the window
`scrollbars`	boolean	display scrollbars if the document is larger than the window
`resizable`	boolean	allow the window to be resized
`width`	integer	the width of the window (in pixels)
`height`	integer	the height of the window (in pixels)
`top`	integer	the top position of the window (in pixels)
`left`	integer	the left position of the window (in pixels)

Using this list of optional parameters, we can create a huge variety of windows with different properties. The next few lines of VBScript code create some interesting new windows. Try pasting them into a page and running them to see what you get.

  Window.Open "http://www.wrox.com/", "myWindowOne", "toolbar=no, menubar=no, location=no, directories=no"
Window.Open "http://www.wrox.com/", "myWindowTwo", "width=100, height=100, resizable=no"
Window.Open "http://www.wrox.com/", "myWindowThree", "menubar=no, toolbar=yes, location=yes"

"Browser created by Window.Open: with no toolbar, menubar, location, or directories"

"Browser created with Window.Open: has location and toolbar, but no menubar"

The value of each parameter that we don’t define is unpredictable, so be sure to explicitly turn on or off each feature you do or don’t want to appear in your new window.

In the Window.Open code we’re ignoring the return value of the Open call. This is fine if we don’t care about what happens to the window we’re creating. However, if we want to manipulate it after the Open call, we need to save a reference to the window. Fortunately, Open’s return value is just this reference. We'll show you an example of this in the next section.

The Close Method

The Close method doesn’t have the variety that the Open method does, but it’s still powerful. For example it can end a user’s session, and shut down their browser! Admittedly, in most cases, this would be rather rude—but it does have its uses. In addition to closing the current browser window, it can be used to close other windows that we’ve opened with a call to the Open method. We just need be sure to save a reference to the windows when we open them.

Enter the following code into a new file and save it:

  <HTML>
<HEAD>
<TITLE> Window Open And Close Tester </TITLE>
</HEAD>
<BODY>
<CENTER>
<H1> Window.Open And Window.Close </H1>
<INPUT TYPE="BUTTON" NAME="btnOne" VALUE="Open One">
<INPUT TYPE="BUTTON" NAME="btnDOne" VALUE="Close One"><p>
<INPUT TYPE="BUTTON" NAME="btnCloseMe" VALUE="Close Me">
<SCRIPT LANGUAGE="VBScript">
Dim objNewWindow
Sub btnOne_onClick
  Set objNewWindow = Window.Open("http://www.wrox.com/", "myWindowOne", "toolbar=no, menubar=no, location=no, directories=no")
End Sub    
Sub btnDOne_onClick
  objNewWindow.Close
End Sub
Sub btnCloseMe_onClick
  Window.Close
End Sub
</SCRIPT>
</CENTER>
</BODY>
</HTML>

Next load it into your browser:

When this page loads, we see three buttons. Try clicking the Open One button. After a moment, we see a new browser window (incidentally, without a menubar, toolbar, location text box, or extra link buttons) appear on our screen. Now press the Close One button, and our new window disappears. Don’t press the third Close Me button just yet! We don’t want to shut down this browser until we’re done experimenting with the code.

The explanation for this behavior is in a few lines of code. First, we declare a variable called objNewWindow to store the reference to the window we’re going to create. Then our Window.Open method actually creates the window, returning a reference to be stored in objNewWindow:

  Dim ObjNewWindow
Sub btnOne_onClick
  Set objNewWindow = Window.Open("http://www.wrox.com/", "myWindowOne", "toolbar=no, menubar=no, location=no, directories=no")
End Sub

After this our code to close the window is simple, we just use the objNewWindow variable and the Close method:

  Sub btnDOne_onClick
  objNewWindow.Close
End Sub

The code for the third button just shows how Close can be used with the Window object to terminate the current browser instance.

Timers: setTimeout and clearTimeout

These methods of the Window object can be used to execute a function after a certain amount of time. Their use is relatively simple. SetTimeout takes the name of a function, and a time value in milliseconds. After the time value has passed, the function is called automatically.

For example, the following code calls a routine named TimerFunc after 5000 milliseconds (5 seconds):

  ID = Window.setTimeout("TimerFunc",5000)

Once we’ve started a timer with setTimout, we may find that we want to cancel it so that the function specified in the setTimeout call isn't executed. This is where the clearTimeout function comes into play, assuming we’ve saved the return value of the setTimeout function. In the line of code above we’ve saved our return value in a variable called ID, and it’s this variable that we’ll use in our call to clear the timer:

  Window.clearTimeout ID

If we call clearTimeout with an ID value that doesn’t exist, then nothing will happen and any timers we have active will continue to work.

Note that the setTimeout call only executes the function that it is passed once. If we want to have a routine called repeatedly, we need to reset the timer with another setTimeout call within the function that’s called by it.

The Navigate Method

The very useful Navigate method brings us to the end of our Window object odyssey, at least where the non-object properties are concerned. Navigate takes a string parameter and navigates the window object it is called from, to the URL in that string. We saw Navigate in action way back, when we were still talking about connecting code to events. Its use is logical as the line of code below simply redirects the current browser to the URL of the Wrox Press home page:

  Window.Navigate "http://www.wrox.com/"

Note that we’re not limited to using Navigate with just the current Window object. We can also use it in combination with the top, parent, and opener properties to act on other windows or parts of the window – all Navigate requires is that it be called from a valid reference to a Window object.