VTOOL (VTOOL.EXE) is a COM module by ERCC, written to support Windows scripting (esp. VBS). It provides a some visual elements such as a list selection and some functions to use profiles (.ini files). Sample usage can be seen with the script for backup copying (BakCopy), which initially was the cause for writing VTOOL.
The current VTOOL version 1.3.2 (02.2017) provides the following objects.
This object allows to copy text to and from the Windows clipboard, simply using its property Text.
The sample demonstrates usage with the involvement of Windows editor Notepad.
Set CLP = CreateObject("VTool.Clipboard") CLP.Text = "A text is a text is a text." & vbNewLine MsgBox "You now can insert and modify the clipboard text ...", _ , "starting NOTEPAD" Set WSS = WScript.CreateObject("WScript.Shell") WSS.Run "notepad", , vbTrue MsgBox CLP.Text, , "clipboard text:"
DriveList provides a list of currently available drives (drive letters) where the user can select one. The function (method) Selection(default, title) opens a listbox window and returns the selected drive specification (drive letter with colon).
Use the argument default to preselect a valid drive specification.
The optional argument title can be used to define the window's caption.
Set obj = CreateObject("VTool.DriveList") var = obj.Selection("D:")
Note: Most often drives are not listed with their respective labels. The above-mentioned backup script contains statements (commented out) that use FileSystemObject functions together with the List object to create a different drive list.
This object can be applied to record events. It creates informational entries either in the Windows application event log or in a log file. (Because this object is based on the corresponding functionality of Visual Basic, it doesn't provide all the capabilities of Windows event logging.) So VTOOL supplements WshShell's LogEvent method.
The properties File and Mode optionally determine the target place for event recording. File specifies a log file (which is a text file) for output. Mode can be given the following values:
|0 (default)||The output destination depends on Windows. For all NT-based versions this is the system's event log, otherwise it's a log file.|
|1||Output is written to Windows event log. VBRunTime will indicate the application source and VTOOL —along with the given text— will be part of the event description.|
|2||Output is written to a log file. If File doesn't define a file name, the name vtool.log will be used. If no path is specified, the file will be created in the WINDOWS folder.|
The function Report(text, type) logs an event with text as (trailing) part of the description. An empty string will produce an error.
The optional parameter type can define one of the following event types:
The EventLog.Report and WshShell.LogEvent methods are quite similar in use and results:
Set obj = CreateObject("VTool.EventLog") obj.Report "Log-Entry created by VTOOL", vbInformation Set obj = CreateObject("WScript.Shell") obj.LogEvent 1, "Log-Entry created by WShell"
The event description created by LogEvent is more straightforward and clear. The application source here is WSH (Windows Script Host).
Additionally VTOOL can accomplish logging to a text file. The file will be created if it doesn't exist. New entries are appended to the end. Note that date and time values are not included automatically. So if you want them to be recorded, you have to pass them with the log text. And the same goes for the application name.
The following example uses a log file in the current folder and creates a log entry. The user-defined part of the text is separated by a line break.
Set obj = WScript.CreateObject("WScript.Shell") var = obj.CurrentDirectory If Right(var, 1) <> "\" Then var = var & "\" Set obj = CreateObject("VTool.EventLog") With obj .Mode = 2 .File = var & "vtool-test.log" .Report vbNewLine & "TESTSCRIPT " & Now & _ " This is a new record for our log file." End With
This is the generalized form of a list box window where the user can select items.
Selection(items, default, title) opens a list box window and returns the selected item(s). If the user cancels the selection, an empty string is returned.
List entries are defined by a single string items with newline characters as delimiters. When dividing the items the function will ignore empty parts.
Use the optional argument default as a zero-based index to initialize a selection.
The optional argument title defines the window's caption.
abc = "alpha" & vbNewLine & "beta" & vbNewLine & "gamma" ' & vbNewLine Set obj = CreateObject("VTool.List") var = obj.Selection(abc, , "Choose your letter")
By default the property MultiSel is False (0) and only a single list entry can be selected. The setting True allows the selection of multiple entries. In this case a preset index is meaningless. The selected items are again newline-separated parts of the returned string.
var = "Love means never having to say you're sorry." var = Replace(var, " ", vbNewLine) Set obj = CreateObject("VTool.List") obj.MultiSel = vbTrue var = obj.Selection(var, , "List box with some words") Set obj = Nothing MsgBox var
This object gives some details about the current VTOOL process. The following properties can be read:
About holds a brief program information, hInstance is the handle of the process instance (module), Path returns the program's directory, and ThreadID is the thread identifier of the current thread.
Set obj = CreateObject("VTool.Me") WScript.Echo "About = " & obj.About WScript.Echo "Path = " & obj.Path WScript.Echo "hInstance = " & obj.hInstance WScript.Echo "ThreadID = " & obj.ThreadID Set obj = Nothing WScript.Quit (0)
Because it's often easier and more suitable to use a simple .ini file ("INI") for storing parameters, this object provides somewhat basic profile functionality, giving the opportunity to read and write values (strings).
The property File specifies a file to be used as an initialization file. The file name must be defined before any subsequent access. If the file does not exist, VTOOL immediately raises an error. (This is because the underlying Windows API function otherwise doesn't reliably indicate profile errors.)
Use GetValue(section, key) to read a key's value, and GetSection(section) to read all values of the given profile section. GetSection returns a single string where the items are delimited by newline characters and can easily be splitted (see the backup copy script mentioned above).
Set obj = CreateObject("VTool.Profile") With obj .File = "sample.ini" var1 = .GetValue("department-1", "entry-1") var2 = .GetSection("department-2") End With
The function SetValue(section, key, entry) writes a single key entry (string) into the specified section of the defined INI file, creating the section if necessary.
The function returns the boolean value of the API function, where a nonzero value indicates success. Some —not all— failures are indicated by the return value zero (0, False), e.g. a write-protected INI file.
The following sample shows how to start with a new INI file:
profile = "C:\Apps\xtest.ini" Set obj = CreateObject("Scripting.FileSystemObject") Set obj = obj.CreateTextFile(profile, True) obj.Close Set obj = CreateObject("VTool.Profile") obj.File = profile var = obj.SetValue("chapter", "alphabet", "abc")
To facilitate continuous text output VTOOL provides a simple modeless window. Of course using such a window is reasonable only during prolonged procedures. Keep in mind that the script execution doesn't stop. For a pause use MsgBox, WScript.Sleep, or the like.
Create(title) creates (shows) an empty austere window. The optional argument defines the window's caption, which also can be accessed with the Title property.
Calling the function WriteLine(text) prints (appends) a new line of text inside the window's client area. This is of no effect if the window isn't created.
The properties WriteSize and WriteBold can be used to set (change) the respective font attributes. The size is specified in points and can take a value between 6 and 36, the default is 10. The bold style is determined by a boolean value, False as default. Note that these settings affect the entire text.
Cls() clears all text output. Remove() removes the window.
Set obj = CreateObject("VTool.Window") obj.Create obj.Title = "This is a text output window" obj.WriteLine "ABC, easy as: one, two, three" obj.WriteLine "Or simple as: Do Re Mi" obj.WriteLine "ABC, one, two, three, baby, you and me!" MsgBox "Let's have a break here ...",, "VTOOL-WINDOW" obj.Remove Set obj = Nothing
Because the display of text output is restricted to the visible window's area, parts of longer text may be hidden. While it is possible to resize the window if the script pauses, there's no way of scrolling the content. The Window2 object, described subsequently, provides an optional scroll bar.
This object is similar to Window, except that it uses a (read-only) edit control with an optional scroll bar for displaying text. To enable scrolling, set the property Scroll to True before creating the window. This will add a vertical scroll bar.
The example uses this feature to display a text file.
Const TEXTFILE = "C:\Data\sample.txt" Set file = CreateObject("Scripting.FileSystemObject") Set file = file.OpenTextFile(TEXTFILE, 1, 0, -2) Set win = CreateObject("VTool.Window2") win.Scroll = True win.Create "Content of " & TEXTFILE Do While Not file.AtEndOfStream win.WriteLine file.ReadLine Loop file.Close MsgBox "Okay!",, win.Title win.Remove
Note: Although text display is read-only, it still features a text cursor (caret), and the user can select text for copying.
Usage in scripts etc.
Please consider that VTOOL's variables are typed, while those in client environments may not. Within VBScript, for example, all data is of type Variant. So it may be necessary to cast a variable to the specific data type before passing it to VTOOL:
Set obj = CreateObject("VTool.Window") obj.Create obj.WriteLine CStr(VariableX)
VTOOL is provided as freeware and "as is" without any warranty or liability. Of course, suggestions for improvements are welcome.
The file vtool.zip contains VTOOL.EXE along with this description (VTOOL.CHM).
For installation it suffices to extract this content to a folder of your choice. As a COM module VTOOL has to be registered once, which can simply be done by invoking the program file. (Conversely this registration should be undone before removing VTOOL.)
will show possible arguments.
Note that the registration generally requires administration rights. The recommended procedure is to open a console window ("Command Prompt") as Administrator and then enter the instruction
VTOOL requires the VB6 runtime files which are normally included with Windows (but also available as download).