Günter
BornGünter
BornThe following document describes the WinExt object model of the WSHExtend ActiveX control. WSHExtend is an ActiveX control which extend the WSH with additional objects, methods and properties. I have developed this control within my Inside Windows Script Host book published by Microsoft Press Germany. To allow the public to use the extensions, I have decided to localize the control into English and release the OCX file (see below) and this documents in the internet. The source code and many samples are released in my German book (and also my English version of this title "Windows Scripting Host Tutorial" contains the samples).
The initial release of WSHExtend was version 1.0, which I have published in whole within my WSH book (Inside Windows Scripting Host, Microsoft Press Germany). Then I have localized the control and this document in English. After releasing the control on my website I got a message from Kjell Nilsson, who pointed out that a sample won't run, if variables are passed as parameters. The reason: My control uses typed variables within the methods, whilst Windows Scripting Host programs contain only Variant variables. My first attempt failed, I changed the WSHExtend object to use Variant parameters within the methods and do the necessary parameter conversion internally. Unfortunately the control was posted a few days on my web-site. After a day I found out two problems with the version 1.2: First of all some samples I created to use the WSHExtend control failed (I haven't found out till now what exactly has happened - but there are some problems with type conversions - and I haven't the time to investigate it now). And the second trap: Calling this ActiveX control from Visual Basic or VBA requires that all parameters must be passed as variants. So I decide to bring back version 1.0 or the control and amend the Programmers Reference.
During writing the English Version of my WSH Tutorial I undertok the control a heavy revision. Extensive handling for run-time errors and checkings for submitted parameters are added. The result is Version 2.0.1, which is also available for download.
The ActiveX control WSHExtend (WinExtend.ocx) contains the object WinExt, which extends the Windows Scripting Host. Below is a short reference of the WinExt 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("WSHExtend.WinExt")
and in JScript with the following statement:
var objAdr = WScript.CreateObject("WSHExtend.WinExt");
Then you may use the object variable objAdr to access the methods and properties.
The WSHKeyExist method
This method may be used only in VBScript and checks whether a Registry key exists. The method uses the following syntax:
obj.WSHKeyExist(Root, key) = bstatus
The parameter Root is of type Variant and contains the code for the Root key, which must be defined in VBScript as:
Const HKEY_CLASSES_ROOT = &H80000000 Const HKEY_CURRENT_USER = &H80000001 Const HKEY_LOCAL_MACHINE = &H80000002 Const HKEY_USERS = &H80000003 Const HKEY_PERFORMANCE_DATA = &H80000004 Const HKEY_CURRENT_CONFIG = &H80000005 Const HKEY_DYN_DATA = &H80000006
The parameter key is of type Variant and contains the key whose existence may be checked. The method returns a Boolean value either true (exist) or false (entry not found).
' Create WSHShell object, required for Registry access
Set WSHShell = WScript.CreateObject("WScript.Shell")
' Create object for the WSH extension WSHKeyExist
Set objAdr = CreateObject("WSHExtend.WinExt")
' Ask user for a file name extension
key1 = InputBox ("Please enter a file name extension " + _
"(for instance .bmp)", "File name extension",".bmp")
If key1 = "" Then WScript.Quit
' Test, whether key exists
If objAdr.WSHKeyExist (HKEY_CLASSES_ROOT, key1) Then
key = WSHShell.RegRead ("HKCR\"+key1+"\")
The WSHKeyExist1 method
Same function as WSHKeyExist, but supports both VBScript and JScript. The method uses the following syntax to check the existence of a key:
obj.WSHKeyExist1(Root, key ) = bstatus
The parameter Root is of type Variant and contains the code for the Root key (type Variant) as a string (may be "HKCR", "HKCU", "HKLM" or "HKU"). The parameter key contains the key or value, whose existence may be checked. The method returns true (entry found) or false (entry not found).
NOTE:The WSHKeyExist method doesn't check whether a value exists or not. If you need to check this, use the RegRead method with run-time error handling.
The WSHInputBox method
This method implement the VBScript InputBox function for all WSH languages (JScript for instance). The method uses the following syntax:
obj.WSHInputBox(Prompt, title, Default) = result
Prompt (type String) contains the string which shall be displayed. In title (type String) we submit the title text for the dialog box window. The parameter Default is a Variant and defines the value shown in the input box of the dialog. The method submits the parameters directly to the Visual Basic InputBox function and returns the user input.
Dim objAdr
objAdr = WScript.CreateObject("WSHExtend.WinExt")
WScript.Echo objAdr.WSHInputBox("Enter a value", "WSH sample",6)
If you use variables as parameters in VBScript or JScript programs, you may use the same scheme:
Dim objAdr, text, title, value
objAdr = WScript.CreateObject("WSHExtend.WinExt")
text = "Enter a value"
title = "WSH sample"
value = 6
WScript.Echo objAdr.WSHInputBox(CStr(text), CStr(title), value)
I have used the CStr function to convert the Variant variable to a string, before the parameters text and title are passed to the method. If you forget this parameter conversion, the WSH reports a type mismatch using this method.
The WSHSendKeys method
This method implements a SendKeys function, which simulates key strokes and send them to the window which has the focus. We use the following syntax:
obj.WSHSendKeys(keys, Wait)
The first parameter keys (type String) contains the string with the key strokes to be send. If Wait (bool) is set to true, the method waits, till the string is processed. With false the method returns immediately after sending the string.
Dim objAdr
objAdr = WScript.CreateObject("WSHExtend.WinExt")
objAdr.WSHSendKeys "ABC",true
My WSH book discusses the details of this method. Here is a short sample:
var WSHShell = WScript.CreateObject("WScript.Shell");
var Wsh = WScript.CreateObject("WSHExtend.WinExt");
// launch Windows calculator
WSHShell.Run ("Calc.exe");
WSHWait (200); // just wait a little bit
Wsh.WSHSendKeys ("10", true);
Wsh.WSHSendKeys ("{+}", true);
Wsh.WSHSendKeys ("2", true);
Wsh.WSHSendKeys ("=", true);
WSHWait (500);
Wsh.WSHSendKeys ("c", true);
for (var i = 1; i <=3; i++)
{
Wsh.WSHSendKeys (i, true);
Wsh.WSHSendKeys ("{+}", true);
}
WScript.Echo ("Terminate?");
WSHWait (200);
Wsh.WSHSendKeys ("%{F4}", true); // close calc with Alt+F4
The following program demonstrates the use of the WSHSendKeys method with variable passing. We invoke the Windows editor and write a string into the editor's window:
DIM WSHShell, objAdr, strkeys
' create objects
Set WSHShell = WScript.CreateObject ("WScript.Shell")
Set objAdr = WScript.CreateObject("WSHExtend.WinExt")
WSHShell.Run "Notepad.exe" ' launch Windows editor
objAdr.WSHWait 200 ' just wait a little bit
' first attempt to write a string into the editor window
objAdr.WSHSendKeys "The quick brown fox" + vbCRLF, true
' second attempt to write a string into the editor window,
' now we use variables, so we must convert the type to a string
strKeys = "Here again: The quick brown fox"
objAdr.WSHSendKeys CStr(strKeys), true
WScript.Echo "Ready"
I have used the CStr function to convert the Variant variable StrKeys to a string, before the parameters are passed to the method. If you forget this parameter conversion, the WSH reports a type mismatch using this method.
Beside the normal printable characters you can force WSHSendKeys to send also keystrokes like Enter, Tab, F1 and so on. These keystrokes must be coded with escape characters. Each escape sequence is enclosed in braces { }. The following list contains the names of these keys.
Key Code
{BACKSPACE}, {BS} or {BKSP}
{BREAK}
{CAPSLOCK}
{DELETE} or {DEL}
{DOWN}
{END}
{ENTER}or ~
{ESC}
{HELP}
{HOME}
{INSERT} or {INS}
{LEFT}
{NUMLOCK}
{PGDN}
{PGUP}
{PRTSC}
{RIGHT}
{SCROLLLOCK}
{TAB}
{UP}
{F1}
{F2}
{F3}
{F4}
{F5}
{F6}
{F7}
{F8}
{F9}
{F10}
{F11}
{F12}
{F13}
{F14}
{F15}
{F16}
For example insert the code "{F16}" in SendKeys to send the key F16. You may combine key combinations with the Shift, Strg or Alt key. In this case the escape character for the key code must be preceded by the following prefix code:
Key Code Shift + Strg ^ Alt %
If you like to send a key combination of Shift, Strg or Alt with another key,
enclose the escape sequence with parenthesis. Shift + F1 must be send as
"+{F1}", but the key combination E+C must be send as
"+(EC)". If you need to press Shift+E and then C separate, use the
code "+EC" (+ is associated with the following code, whilst the 2nd
character is interpreted as a separate code).
Repeating keystrokes may be given as {key counter}. A space between key and
counter is recommended. {LEFT 42} simulates pressing 42times the Left key, {h
10} means: send the key "h" ten times.
The WSHWait method
This method suspends the script for a given time (without using the processor during this time). We use the following syntax:
obj.WSHWait(Wait)
The parameter Wait (type Long) contains the delay time in Milliseconds.
Dim objAdr
objAdr = WScript.CreateObject("WSHExtend.WinExt")
objAdr.WSHWait 1000 ' Wait 1 second
The WSHWait method doesn't use any CPU time during wait, because the whole process is suspended for the delay time!
The WSHAppActivate method
This method allows to switch an already running application and its window into the foreground. We use the following syntax:
obj.WSHAppActivate(title)
The parameter is of type Variant and must contain the ProcessID (returned from the WSHShell method) or the window title.
Dim objAdr, procID
objAdr = WScript.CreateObject("WSHExtend.WinExt")
procID = objAdr.WSHShell("Calc.exe", 1) ' launch calc
objAdr.WSHAppActivate procID ' set focus to calculator
The WSHShell method
This method launches an application and returns the ProcessID (which is needed by the WSHAPPActivate). Use the following syntax:
obj.WSHShell(path,style)
The parameter path (type String) defines the path and name of the application to launch. The parameter style (type Integer) defines the window style as:
| vbHide 0 | Hide Window |
| vbNormalFocus 1 | Window get focus. |
| vbMinimizedFocus 2 | Window minimized and with focus. |
| vbMaximizedFocus 3 | Window maximized and with focus. |
| vbNormalNoFocus 4 | Restore Window, don't set focus. |
| vbMinimizedNoFocus 6 | Window minimized, don't set focus. |
The following code demonstrate how to use the method:
Dim objAdr, procID
objAdr = WScript.CreateObject("WSHExtend.WinExt")
procID = objAdr.WSHShell("Calc.exe", 1) ' launch calc
objAdr.WSHAppActivate procID ' set focus to Calc
The WSHBeep method
The method creates a beep massage, using the following syntax:
obj.WSHShell (mode)
The parameter Mode is of type Variant and defines the beep mode:
0 = PC speaker 1 = MB_ICONASTERISK 2 = MB_ICONEXCLAMATION 3 = MB_ICONHAND 4 = MB_ICONQUESTION 5 = MB_OK
The following code demonstrates the use.
Dim objAdr, procID
objAdr = WScript.CreateObject("WSHExtend.WinExt")
objAdr.WSHBeep 0
We create a beep on the PC speaker.
The WSHFindWindow method
The method returns the handle to the window, using the following syntax:
obj.WSHFindWindow(WinName) = hWnd
The parameter WinName is a variant and contains the window title. If the returned value is 0, no window with this title exists. Otherwise the returned value contains the handle of the window, which may be used in other methods.
The WSHFlashWindow method
The method flashes a given window or the button in the taskbar. We use the following syntax:
obj.WSHFlashWindow(hWnd, flag) = bstatus
Both parameters are of type Variant. The parameter hWnd contains the window handle (see WSHFindWindow method). The flag specifies the window mode (flag=true highlight the title bar, flag=false show title bar normal).
The WSHMoveWindow method
Allow to move or resize a window, using the following syntax:
obj.WSHMoveWindow(hwnd, x, y, b, h) = bstatus
The parameter hWnd is the window handle passed as a variant (see WSHFindWindow method). The parameters x and y defines the upper left corner position of the window in pixel. In b, h we must submit the window with and height. The method returns a status code (boolean) indication either success of failure.
The WSHSetForegroundWindow method
The method switches a windows in the foreground, using the following syntax:
obj.WSHSetForegroundWindow(hwnd) = bstatus
The parameter hWnd contains a window handle as a variant (see WSHFindWindow method). The method returns the status (boolean), indication a success (true).
The WSHExitWindows method
Allow to shutdown, logoff or restart Windows 95/98. Use the following syntax:
obj.WSHExitWindows(code) = bstatus
The parameter code (type Variant) defines the mode (0 = logoff, 1 = shutdown, 4 = restart). An example may be found in the book.
The WSHPlaySound method
Allows a sound output per script, using the following syntax:
obj.WSHPlaySound(com, flag) = bstatus
The parameter com (type String) must contain the sound file ("C:\Tada.Wav"). Flag (type Long) specifies the play mode (0 synchrony, or 1 asynchrony). The method returns the state (boolean) to show the success.
The WSHMciExecute method
Allows a sound output using the following syntax:
obj.WSHMciExecute(com) = bstatus
The parameter com (type String) must contain the sound file ("Play C:\Tada.wav"). The method returns the state (boolean) to show the success.
The WSHFileDialog method
Shows a file select dialog box. Use the following syntax:
obj.WSHFileDialog(dr1) = bstatus
Submit the drive (type Variant) within the parameter dr1 ("C:\"), which shall be shown in the dialog box. The method returns a status code indicating whether the user has selected a file (code = true) or choose Cancel (result = false). If a file is selected, retrieve the selection using the properties DriveName, FolderName and FileName.
The WSHAbout method
Shows the about dialog box:
obj.WSHAbout
The WSHAbout1 method
Same as WSHAbout, but implemented in a different way.
obj.WSHAbout1
The WSHExtend ActiveX control comes AS-IS without any warranty and support. I haven't tested all methods under Windows NT, so it can be that some methods won't work under this operating system (for instance the method to exit Windows, because Win NT requires additional stuff to get permission for a restart - and I was too lazy to implement it). Use the control for free but 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 modules may be freely distributed in the internet under the condition that this Programmers Reference is included, that all files contained in the ZIP-Archive are shiped and that the WSH Bazaar with its URL http://www.borncity.de is mentioned as the source of the control. Distribution on CDs or with commercial products requires a written permission from the author.
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 (which are part of the distribution). I have created three different methods on my web-site for download and install the control: If you already have dowloaded and installed WSHExtend.zip, the run-time is available. In this case you need to download only the OCX-file and install it (this comes handy during upgrading to new versions).
After installing WSHExtend you can use the WinExt
object and its methods as described above.
top
by (c) Günter Born changed 10-June-1999