Günter Born

WSHForms Programmer's Reference

This reference describes the Form1 object model of the WSHForms ActiveX control. WSHForms is an ActiveX control which provides a simple form and an about dialog for WSH script. The foundation of this control was discussed within my book Windows Script Host Tutorial. Within this book I have shown how to use forms with buttons, text boxes, list boxes and more within WSH scripts. But this requires also that a script programmer deals with the form's source code - a task not always welcome to many programmer. I saw many requests for a simple login dialog retrieving a user name and a password. Therefore I have modified the control in a manner that a script programmer can use it without accessing the source code to display a predefined form. The OCX file (see below) and this reference are released to the public in the internet. The source code of the original control and many samples may be found in my Windows Scripting Host Tutorial.

Version Info

The initial release of WSHExtend is version 1.0, which is available for download now.

The Form1 object model

The ActiveX control WSHForm (WSHForm.ocx) contains the object Form1, which extends the Windows Scripting Host with a simple form. Below is a short reference of the Form1 object model, describing the methods and properties.

Using the object

The object may be created in VBScript with the following statement:

Dim objAdr
Set objAdr = WScript.CreateObject("WSHForm.Form1")

and in JScript with the following statement:

var objAdr = WScript.CreateObject("WSHForm.Form1");

Then you may use the object variable objAdr to access the methods and properties.

The About method

This method allows you to invoke an About dialog box. The method requires one array parameter to invoke the dialog.

objAdr.About(Param1)

The method contains a basic About dialog, which shows information about the control and the version of the ActiveX-Control. Use this code to invoke the following dialog:

Dim Param1
Param1 = array ("")
Set objAdr = WScript.CreateObject("WSHForm.Form1")
objAdr.About (Param1) ' invoke the basic About dialog

The array Param1 gets initialized with one empty string. Note that the argument containing the array needs to be enclosed in VBScript in parantheses (). If the parantheses ares missing, VBScript causes a run time error. If the method detects this empty string in the parameter, the following dialog is shown.

Probably a script programmer intends to show a customized About dialog during script execution. Voila, this can be done submitting an array with the following parameters to the method:

array(0)	A string defining the Form's caption
array(1)	A string defining the Label 1 (right of the icon) within the form
array(2)	A string defining the Label 2 (below the icon) within the form
array(3)	A path to an image file (formats: bmp, ico, gif)

The array may have one, two, three or four items, which you may use to customize the content of the About dialog box. The following code sets only the Form's caption:

Dim Param1
Param1 = array ("Hello World")
Set objAdr = WScript.CreateObject("WSHForm.Form1")
objAdr.About (Param1) ' invoke the basic About dialog

Within the following code listing I have used three different calls to the About method. The first call invokes the basic dialog whilst the other two dialogs are customized.

Take care to the name of the icon file, if you use the fourth parameter. If the path is illegal, the method displays an error message. And here comes the code listing of the sample.

'************************************************
' File:    About.vbs (WSH sample in VBScript) 
' Author:  Günter Born
'
' Demonstrates how to use an about box.
' Attention: Requires WSHForm-ActiveX control.
'' Check out Born's Windows Scripting Host Bazaar at:
' http://www.borncity.de
'
' In no way shall the author be liable for any
' losses or damages resulting from the use of this
' program. Use AS-IS at your own risk.
'
' The code is the property of the author. You may
' use the code and modify it, as far as this header
' remains intact. Further updates and other samples
' may be found on my site mentioned above.
'************************************************
Option Explicit

Dim objAdr
Dim Param1, Param2, Param3

' Init Form's content, parameters are: 
'   Caption Form 
'   Caption Label1
'   Caption Label2
'   Path to Image file (bmp, ico, gif)

Param1 = array ("")
Param2 = array ("Born's Input Form Version 1.0", _
                "About: WSHForm.ocx is an ActiveX control", _
                "Using Forms within WSH Scripts", _
                "E:\WSH\Samples\Unsupported\Tools.bmp")

Param3 = array ("About My Turtle Killer Script Version 1.0", _
                "This Killer script cleans your hard disk," & vbCRLF & _
                "wipes your desktop and polishes your keyboard", _
                "The script was brought to you by www.microsoft.com", _
                "E:\WSH\Samples\Unsupported\BTurtle.gif")

' Create an object (using the ActiveX control)
' which provides the form

Set objAdr = WScript.CreateObject("WSHForm.Form1")

objAdr.About (Param1)     ' invoke the basic About dialog

objAdr.About (Param2)     ' invoke the customized About dialog

objAdr.About (Param3)     ' invoke the customized About dialog
' End

The TxtInput method

This method provides a simple input form with two text boxes as shown in the following figure. The caption of the two labels and the init values of the text boxes may be customized. Also the second text box may be used for a password input. In this mode all user entries are overtyped with a character (like *). So you can use this dialog either for user input or to request a user name and a password.

To use the method, define the object variable as shown above. Then you have to define the parameters for the form:

Dim Param
Param = array ("Born's Input Form", _
               "Name", "Age", "Hello", "4")
Set objAdr = WScript.CreateObject("WSHForm.Form1")
objAdr.TxtInput (Param)  ' invoke Form

The parameter submitted to the TxtInput method must be an array containing the following values.

array(0)	A string defining the Form's caption
array(1)	A string defining the Label 1 within the form
array(2)	A string defining the Label 2 within the form
array(3)	A string defining the initial value of Textbox 1
array(4)	A string defining the initial value of Textbox 2
array(5)	A string defining an optional password character

The sequence shown above defines only 5 parameters, therefor the form is used for simple input. If the sixt array item is not blank, the character submitted will be used to overtype keybord input. The user input may be retrieved using the GetVal() method:

result1 = objAdr.GetVal(1) ' get input value 1 
result2 = objAdr.GetVal(2) ' get input value 2

The parameter submitted to the method defines the number of the textbox (1 or 2) whose value shall be returned. The next listing shows how to invoke the form and queries a name and an age.

'************************************************
' File:    Form.vbs (WSH sample in VBScript) 
' Author:  Günter Born
'
' Demonstrates how to use an about box.
' Attention: Requires WSHForm-ActiveX control.
' Check out Born's Windows Scripting Host Bazaar at:
' http://www.borncity.de
'
' In no way shall the author be liable for any
' losses or damages resulting from the use of this
' program. Use AS-IS at your own risk.
'
' The code is the property of the author. You may
' use the code and modify it, as far as this header
' remains intact. Further updates and other samples
' may be found on my site mentioned above.
'************************************************
Option Explicit

Dim objAdr
Dim Param
Dim result1, result2
Dim Title, Text

Title = "WSH sample forms input - by G. Born"
Text = "You entered:" + vbCRLF + vbCRLF

' Init Form's content, parameters are: 
'   Caption Form 
'   Caption Label1
'   Caption Label2
'   Value Textbox1
'   Value Textbox2

Param = array ("Born's Input Form", _
               "Name", "Age", "Hello", "4")

' Create an object (using the ActiveX control)
' which provides the form

Set objAdr = WScript.CreateObject("WSHForm.Form1")

objAdr.TxtInput (Param)  ' invoke Form

' get results
result1 = objAdr.GetVal(1)     ' get input value 1
result2 = objAdr.GetVal(2)     ' get input value 2

' show results
MsgBox Text & result1 & vbCRLF & result2,,Title 

Set objAdr = Nothing
' End

If the sixth item of the array is set to a character (for instance "*"), the user input is overtyped. This can be used for a password input.

The following code listing demonstrates how to use the form for a password input.

'************************************************
' File:    Passw.vbs (WSH sample in VBScript) 
' Author:  Günter Born
'
' Demonstrates how to use form input in WSH with
' a password character box.
' Check out Born's Windows Scripting Host Bazaar at:
' http://ww.borncity.de
'
' In no way shall the author be liable for any
' losses or damages resulting from the use of this
' program. Use AS-IS at your own risk.
'
' The code is the property of the author. You may
' use the code and modify it, as far as this header
' remains intact. Further updates and other samples
' may be found on my site mentioned above.
'************************************************
Option Explicit

Dim objAdr
Dim Param
Dim result1, result2
Dim Title, Text

Title = "WSH sample forms input - by G. Born"
Text = "You entered:" & vbCRLF & vbCRLF

' Init Form's content, parameters are: 
'   Caption Form 
'   Caption Label1
'   Caption Label2
'   Value Textbox1
'   Value Textbox2
'   PasswordChar for Textbox2 (optional)

Param = array ("User Login", _
               "Name", "Password", "Administrator", "","*")

' Create an object (using the ActiveX control)
' which provides the form

Set objAdr = WScript.CreateObject("WSHForm.Form1")

objAdr.TxtInput (Param)  ' invoke Form

' get results
result1 = objAdr.GetVal(1)     ' get input value 1
result2 = objAdr.GetVal(2)     ' get input value 2

' show results
MsgBox Text & result1 & vbCRLF & result2,,Title 

Set objAdr = Nothing
' End

Terms of use

The WSHForm ActiveX control comes AS-IS without any warranty and support. Use the control at your own risk. In no case the author will be liable for damages or losses or whatever else resulting from the use of this component. The OCX module may be freely distributed under the condition that this Programmers Reference is included and that the WSH Bazaar with its URL http://www.borncity.de is mentioned as the source of the control.

Download and install

Download the OCX file and install it on your machine. Because the ActiveX control was developed under VB, it needs the VB 5 run-time libraries. If you have ever installed the WSHExtend control, these run-time libraries are available. Then is is sufficient to download the ZIP-archive, unzip the files into a local folder and run RegisterOcx.bat to install the control.

WSHForm.zip (16 KB): Only the raw OCX file, two BAT files and some test files in VBScript. Unzip the Archive into a separate folder. The file RegisterOcx.bat registers your OCX file. Use UnRegisterOcx.bat to remove all Registry entries for this component. Use About.vbs to test whether the control is installed properly. This distribution works only, if you have installed already the VB 5 CCE (or VB 5) or if you have installed the WSHExtend ActiveX control (with the run-time library).

After installing WSHForm you can use the Form1 object and its methods as described above.
top

by (c) Günter Born changed 02-April-2002