Script Template is intended, not for beginning scripters, but for programmers who are new to scripting with Window-Eyes and would like a jump start that addresses most components that are commonly needed by a script. General knowledge about programming constructs, data types, and VBScript syntax is assumed.
To create a new script, save ScriptTemplate.vbs and ScriptTemplate.xml to files with the same extensions but different base names, e.g., to NiftyScript.vbs and NiftyScript.xml.
Enter various script properties in the XML file, including script name, version, and help text. Be careful about characters like ampersand, apostrophe, quote, and equals, which must be represented in a special XML format rather than literally. Define the layout of a custom dialog if one is used by the script.
In the new VBS file, fill in blocks of code surrounded by comments like
Start custom part1
End custom part 1
The 4 custom parts do the following:
(1) initialize global variables and events,
(2) handle hotkey commands,
(3) handle custom dialog events, and
(4) define additional routines.
If your script does not use hotkeys or a custom dialog, those parts are not needed. The variable oHomer is available for calling methods of the Homer Shared Object library, but those methods are not actually used in the code of ScriptTemplate.vbs. Its support functions implement best-practice script features such as the standard help dialog, hotkey manager, key describer mode, monitoring of shared objects, and error reporting.
When the working model of Script Template is running, press Control-Windows-S to invoke a sample dialog containing a list box, edit box, and buttons. Select an item, edit the text, and activate a button. Your choices are then displayed in a message box that shows results of the dialog.
The rest of this documentation provides further detail about the concepts and code behind this script template. It uses three files with the same root name and different extensions. The .vbs file contains programming code in the VBScript language. The .xml file contains meta data about the script (e.g., script name, version, and author), hotkey definitions, and a custom dialog definition if needed. The .ini file contains user-specific configuration data such as whether to check for an update on startup, and non-default hotkey assignments chosen via hotkey manager.
Each hotkey of a script has three attributes corresponding to its key name, command, and description. For example, the sample hotkey has these attributes:
Name = Control-Windows-S
Command = Script Template
Description = Invoke a sample custom dialog
conventions related to these attributes are as follows. The name is a combination of modifier keys and the primary key, seperated by a hyphen character (-). Modifiers are in alphabetical order before the primary key, except that if the Numpad modifier is present, it comes immediately before the primary key. Each key is in proper case ( an initial letter is capitalized followed by others in lower case).
The command attribute typically contains up to three words in title case (proper case except for short prepositions). The description attribute is a one line synopsis of what the command does in sentence case (only the first letter capitalized besides proper nouns or upper case abbreviations).
Each key name is unique since it represents a unique combination from the keyboard. The command attribute should be worded to be unique as well. This allows a script to operate primarily on the level of commands, where each command is configurable via hotkey manager to have an associated key name that is different from the default one assigned by the script.
Most of the work done by a script occurs in the functions called HandleCommand and HandleDialog, which are positioned at the top of the .vbs file so they can be reached with minimal navigation. The HandleCommand function includes a Select Case structure that responds to commands that the user has invoked with their associated hotkeys. Before this structure, the function checks whether key describer mode is active, and if so, speaks the key name, command, and description rather than performing the command.
The HandleDialog function responds to events in a custom dialog if the script defines one in the .xml file. The function includes a Select Case structure that monitors events in the dialog. The code for the dialog created event is where initialization tasks may be done such as filling controls of the dialog with default values. Code for button click events executes a default action, invokes help, closes the dialog, or performs another action.
Following the HandleCommand and HandleDialog functions in the .vbs file are the Startup and Setup functions. The Startup function is the first one that the script runs. In it, many properties of the script are stored in a global dictionary object called oData. The data is obtained from the .xml file or calculated at runtime. SetData and GetData are functions for working conveniently with this store of information. Code may be added to the Startup function to perform more initialization tasks. Other support functions exist for reading or writing a configuration option in the .ini file, initializing properties of shared objects, unregistering hotkeys, or inserting them. The HandleShutdown function dereferences global object variables when the script unloads.
The Setup function runs after all shared objects needed by the script have become available. The full names of these objects are listed within the ScriptRequires tag of the .xml file, and they are stored in a global dictionary called oScriptSharedObjects. Code may be added to the Setup function to perform final initialization tasks. One use is for code that is only intended to run when an updated script is loaded for the first time. After this function runs, the entry in oData named ScriptSetup will have a value of True, so other code in the script can check whether all shared objects are available and initialization is complete.
A script relies on several shared objects from GW Toolkit. There is no guarantee that GW Toolkit will load in advance, or even be loaded at all, so the script waits for each object to become available before enabling functionality that depends on the object. The HandleStateChange function monitors what shared objects are being loaded and unloaded.
When the CheckForUpdate object is loaded, the script checks whether an update is available at Script Central if the user configured the script for an automatic check at startup. The CheckForUpdate function performs this check, and it is queued so that any hitch in communicating with the web server does not prevent other functionality of the script.
When the HotkeyManager object becomes available, the script registers its hotkeys within the RegisterKeys function. This function checks the .ini file for assignments saved by hotkey manager. The number of hotkeys defined there is compared with the number defined in the .xml file. If no definitions are found in the .ini file or if the number differs from that in the .xml file, the script uses the default definitions in the .xml file and writes them to the .ini file. Each hotkey definition is then registered and the result is stored in a global dictionary object called oScriptHotkeys. The name of each dictionary entry is the name of the hotkey and the value is the RegisteredKey object that was created.
When the ErrorReporting object becomes available, the script uses its error handling support, such as the ability to send a report to the script author. The ErrorReporting code is only run once because the script stops monitoring that object after it has been used.
If a user invokes the Help and Options dialog of the script via Sscript manager, the script calls the ShowHelp function. It checks whether the StandardHelpDialog and HotkeyManager objects are available, and if so, invokes the standard help dialog. If these objects are not available, the script presents its description and help text in a message box instead. The ScriptHelp tag in the .xml file is the source of documentation for the script.
Supported Languages: English
Minimum Version: Window-Eyes 7.0
Release Date: 5/3/2008
Last Update: 12/2/2008
12/2/2008 11:33:00 AM
Version 3.1 on December 2, 2008
Fixed IsWMIService and RegisterHotkey functions.
- Filename: ScriptTemplate.wepm
- Date: 12/2/2008 11:33:02 AM
- Size: 9.1KB
- Total Downloads: 4297
DISCLAIMER: Ai Squared DOES NOT ASSUME AND IS NOT RESPONSIBLE FOR ANY LIABILITY WHATSOEVER FOR THE CONTENT OF THIS, OR ANY EXTERNAL, APP, THE OPERATION OR CONTENT (INCLUDING THE RIGHT TO DISPLAY SUCH INFORMATION) OF ANY APP, NOR FOR ANY OF THE INFORMATION, INTERPRETATION, COMMENTS OR OPINIONS EXPRESSED IN ANY APP. ANY COMMENTS OR INQUIRIES REGARDING THIS APP ARE TO BE DIRECTED TO THE PARTICULAR PERSON OR PERSONS RESPONSIBLE FOR AUTHORING AND PROVIDING THE APP.