Welcome to the WinKeySim Help Page

Overview

WinKeySim is a keyboard simulator program that can simulate keystrokes to targeted Windows applications. Practically any series of keypresses can be simulated into practically any Windows application, including the Windows Desktop itself. After reading this overview, see the online help file for more details.

Getting Started

When WinKeySim starts, it places an icon into the Status Area, also known as the System Tray, located usually on the lower right-hand side of the screen. Typically, you will find a clock, a speaker volume icon, and an icon for your anti-virus program in the System Tray area. Here is a snapshot of the System Tray on my computer:

(The icon just left of the clock is the WinKeySim icon.)

Right-clicking on the WinKeySim icon brings up a popup context menu. The context menu has a number of predefined menu items, such as Open, Save, Save As, Exit, and Edit SubMenus. It will also include any custom items you will create with the Edit SubMenus dialog box, which pops up whenever you choose the Edit SubMenus menu item. If you select one of your custom menu items, WinKeySim will place the keystrokes associated with that menu item into the keyboard buffer as soon as you click on the target application's window.

Let's see an example of this in action. Right-click on the WinKeySim System Tray icon and select the Edit SubMenus menu item. This brings up the Edit SubMenus dialog box, which will be empty if you haven't yet defined any SubMenu items. Every menu item must be part of a SubMenu and every SubMenu must contain at least one (1) menu item. If the SubMenu is empty, such as when one is first created, WinKeySim automatically creates a new menu item named "NewItem" for you. Menu items contained within SubMenus with a special name, "TopLevel", will be shown in the context menu as top level items. But they are still part of a SubMenu named "TopLevel". Click the button labeled "New Sub" to create a new SubMenu named "NewSub". Rename this SubMenu "TopLevel" by entering "TopLevel" (without the quotes) into the SubMenu Name Box, which is located at the top left corner of the Edit SubMenus dialog box. As you type you will see the name of the SubMenu changing in the SubMenu List Box, which is a list box located just below the SubMenu Name Box. Now enter "My Address" in the SubMenu Item Name Box, which is located to the right of the SubMenu Name Box. You will see the SubMenu Item named "NewItem" by default change to "My Address" as you type the new name for this item into the SubMenu Item Name Box. Now click the OK button to close the Edit SubMenus dialog box. Congratulations! You have just created your first SubMenu item. Now, all that remains is to define the SubMenu item.

Before we define the SubMenu item, however, right-click on the WinKeySim System Tray Icon. Do you see the new top level SubMenu item named "My Address". Look closely, because it is grayed out. WinKeySim has grayed out this item because we haven't yet defined it. Select the Edit SubMenus item from the context menu again. Now, type in your mailing address into the text box labeled "Type in text to be associated..." At this point, your Edit SubMenus dialog box should look something like this:

Hit the OK button when you are finished.

Now, let's go ahead and save our WinKeySim file by clicking on the Save context menu item, giving the name "Example" to our new file. WinKeySim will automatically add the .wky extension to the file for us. Take note also that our "My Address" menu item is now no longer grayed out, since we have defined the text for that item.

We are ready to test out our "My Address" menu item. Open a word processing program, such as NotePad, WordPad, MS Word, etc. This will be our target application. That is, it will be receiving our simulated keystrokes. It is very important that we have our target application open and as our top level window before we select our "My Address" item. Because, immediately after we select an item from our context menu, WinKeySim will insert the simulated keystrokes into whatever application happens to obtain input focus next (usually with a mouse click). With our word processor open, we can now click on the "My Address" menu item in our context menu. Then click on our word processor window at the insertion point where we would like the "My Address" item data to be placed. If all goes according to plan, our text information should have been typed into our word processing program. If not, something went wrong. Go back and try again.

Special Characters

WinKeySim supports two (2) different types of keystroke simulations:

1) Simple Text Method, and
2) Special Character Method.

The above "My Address" item was an example of the Simple Text Method. It works by placing the associated text, in this case a mailing address, into the Windows Clipboard. It then inserts the text into the target application by simulating a Ctrl+V keypress, which by convention, pastes information from the Clipboard into the current foreground application. In fact, the address data is probably still on the Clipboard. Switch back to your word processor application and enter Ctrl+v and your mailing address will probably be pasted into the application again. This can be useful where you wish to paste the same information more than once. The Simple Text Method works better in some cases because it is quicker to use the Clipboard rather than simulating all those keystrokes individually and also because it is simpler to define the associated item text since all that is required is that you type in the data.

The Special Character Method is more flexible, however, because it allows for the insertion of special characters, such as the F1 through F24 keys, Page Up, Insert, Ctrl, Shift, Alt, etc., whereas the only non-alpha-numeric keys supported by the Simple Text Method are the Tab and Enter keys, and then only as part of the embedded text. (Press Ctrl+I to embed a tab when using the Simple Text Method.)

For this example, let's create a login script for an e-mail client program. Suppose our fictional user, John Brown, has an e-mail address that is jbrown@somesite.com and further suppose that his password is jb123. In order to login and check his e-mail, John has to enter "jbrown", followed by the tab key, followed by "jb123", followed by the enter key. It's not a big deal since it's only a few keystrokes, but when you figure John might login to check his mail several times a day everyday for the rest of his life, all those keystrokes start adding up. With a WinKeySim login script, John can login to check his e-mail with three (3) clicks of the mouse. To create John's login script, right click on the WinKeySim System Tray Icon and choose the Edit SubMenus item. We'll make this a top level item since John will be using it very often. We already have a SubMenu named "TopLevel" so we can just click the "NewItem" button to create a new top level item. (If you have already defined other SubMenus, make sure the "TopLevel" SubMenu is selected in the SubMenu List Box.) Now enter a name for our login script in the SubMenu Item Name Box, which should currently contain the text "NewItem". We'll call this new item "e-mail login". Now enter the following into the item definition text area exactly as this:

["jbrown[tab]jb123[enter]"]

Our Edit SubMenus dialog box will look something like this:

Press the OK button when finished. Then, choose Save from the context menu. Note that the Save As.. dialog no longer comes up since we have already given our file a name when he saved it earlier in the tutorial.

Let's take a closer look at our script definition: ["jbrown[tab]jb123[enter]"]

The fact that the definition begins with [" and ends with "] tells WinKeySim that this is a special character script rather than a simple text definition. Each character within the special script definition will be presented to the target application as simulated keystrokes except for the special bracketed tags. The Clipboard will not be utilized at all. Special characters "tab" and "enter" have been embedded into the script definition with the [tab] and [enter] tags. WinKeySim translates these tags into the special character keystrokes they represent. That is, instead of inserting five (5) keystrokes: [-t-a-b-] into the keyboard buffer, WinKeySim will insert only one (1) keystroke, the tab key. WinKeySim understands the following embedded tags:

[tab]
[;comment]   (comment tag will be ignored by WinKeySim)
[!nnn]       (where nnn is the number of milliseconds for WinKeySim to sleep in order to avoid keyboard buffer overflow)
[#nnn]       (where nnn is a base 10 integer representing the hardware scan code of the desired key)
[^str]       (copy the string "str" to the clipboard)
[paste]      (sends a [ctrl]v[ctrl_up] sequence)
['c']        (where c is an alpha-numeric character key, such as a, b, c, 1, 2, 3, etc.)
[enter]
[&nnnPROMPT] (user input-- nnn is a number from 0-9 representing which slot to save user input into and PROMPT is a query string)
[%nnn]       (where nn is a base 10 integer from 0-9 representing which slot to retrieve data from)
[multi]      (use a multi-line edit control to receive user data when using [&nnnPrompt] tags)
[single]     (use a single-line edit control for user input prompts)
[*str]       (str is the default value to place in the user input edit control which receives user input)
[escape]
[up]         (arrow keys)
[down]
[left]
[right]
[F1]         (function keys f1 through f24)
[F2]
...
[F5]
...
[F11]
[F12]
...
[F23]
[F24]
[back]         (back space)
[insert]
[delete]
[home]
[end]
[page_up]
[page_down]
[apps]        (special windows keys)
[left_win]
[right_win]
[ctrl]        (special modifier keys ctrl, alt, and shift require separate [???_up] tags)
[ctrl_up]
[shift]
[shift_up]
[alt]
[alt_up]

All tags are case-insensitive. That is, [home] is the same as [Home] is the same as [HOME]. Note also that the special modifier keys [ctrl], [alt], and [shift] require separate [ctrl_up], [alt_up], and [shift_up] tags due to the nature of these special keys as they are often used in combination with other keys. For example, if you want to send a CTRL+v to a target application, you would use a script definition: ["[ctrl]v[ctrl_up]"]

Likewise, sending a CTRL+SHIFT+F12 to a target application would require the following script defintion: ["[ctrl][shift][f12][shift_up][ctrl_up]"]

WinKeySim handles practically every key that you will ever need to simulate. However, in the event that there is a key that has not been included in the above list, you can still simulate the key if you know the hardware scan code for that key by using the [#nnn] tag. For example, the hardware scan code for the scroll lock key is 145. So you could use [#145] to simulate the Scroll Lock key. Try it!

Here are some other hardware scan codes:

F13       (124)
F14       (125)
F15       (126)
...
F23       (134)
F24       (135)
NUMPAD0   (96)
NUMPAD1   (97)
...
NUMPAD9   (105)
SPACE BAR (32)
SCROLL LK (145)
NUM LOCK  (144)   (due to windows bug, num lock only seems to work with Win NT/2000 -not Win 95/98)

A few of the above tags don't represent keystrokes at all, but are instead interpreted as directives for WinKeySim to perform some function. For example, the [!nnn] tag tells WinKeySim to sleep for nnn milliseconds. This is necessary where your keystrokes cause the target application to perform a relatively time-consuming task. WinKeySim needs to know that it must wait for the target application to complete the task before attempting to feed more keystrokes into the keyboard buffer. As an example, to tell WinKeySim to sleep for 5 seconds, you would use [!5000] in your script definition. It is sometimes useful to insert the sleep tags into a script while you are writing/debugging it so that you have time to follow along as the script runs, insuring for yourself that it is exhibiting the expected behaviour. You can then go in later, after the script is working properly, and trim away the sleep tags to improve script performance.

You might be wondering what the [&nnnPROMPT] and [%nnn] tags are used for. These are user input tags. Users will be prompted to enter information into a popup dialog box whenever the [&nnn] tag is encountered. The entered information is saved into a "slot" for later use. The nnn represents the number of the slot to store the information into. This can be any number between 0 and 9 since only ten (10) slots are reserved for these purposes. PROMPT is a query string that will be displayed in the popup user input dialog box, which provides the user with a hint as to what to type into the box. Later in the script, when [%nnn] is encountered, WinKeySim will insert whatever text the user had typed into the input box associated with this particular slot number. Two (2) additional tags support these tags: they are the [multi] and [single] tags. The user prompt dialog that pops up will either have a single line input edit control or a multi line input edit control. Use the multi line control for such things as paragraphs, addresses, etc. Use the single line control for single line entries, such as phone numbers, names, etc. You can also supply the user with a default value for the user input edit control with the [*str] tag.

Here is a simple example of a script using these tags:

["[*Joe Doe][&0Type in your name.]Your name is [%0]."]

The above example merely brings up a dialog box asking the user to type in his/her name. It then inserts keystrokes into the targeted application based upon this input. For example, if the user had typed "Jane Doe" into the input field, WinKeySim would have placed "Your name is Jane Doe." (without the quotes) into the target application. A great use for this feature might be to create a form letter template. You could design the script to gather specific information from the user and then insert this information into appropriate places in the letter. Here is an example of a form letter template script:

["
[;]
[; Use the multi and single tags to specify multi-line and single-line input boxes]
[; default is single, so we must turn on multi-line boxes using the multi tag]
[multi][&0Type in the recipient's address here:]
[single][&1Is this a Mr. or a Mrs.?]
[&2What is this person's last name?]
[&3What city does this person live in?]
[;]
[; Now we take this information and strategically insert it into our template.]
[;]
[%0][enter][;Recipient's address (can be a multi-line field)]
[enter]
Dear [%1] [%2],[enter][; Example: Dear Mr. Johnson]
[enter]
(Blah blah blah.)[enter]
How is the weather in [%3] at this time of the year?[enter]
(Blah blah blah.)[enter]
[enter]
Sincerely,[enter]
Mark Ganson[enter]
[enter]
"]

You can set the prompt to "=" if you want to prevent the user input dialog from appearing. In such cases, the default value will be used. Here is an example:

["[*John Doe][&0=]Your name is [%0]."]

Here, "John Doe" is set as the default value. The "[&0=]" tells WinKeySim that we don't want to bring up a user input dialog, we just want to accept the default value. This could be useful where you are testing/debuggin a macro definition, but don't want to have to enter data each time. Once you have achieved the desired functionality, you can go in and setup your prompts. That is, you could replace "[&0=] with something like "[&0Type in your name here.]". If you forget to set a default value with the [*default] tag, a default value of "NODEFAULT" will be returned. You must reset the default value each time you use the [&nnn] tag since WinKeySim automatically resets the default value to "NODEFAULT".

Note the usage of the [;comment] tags. WinKeySim ignores comment tags. They are strictly for your own convenience. Some of these tags can be somewhat on the cryptic side. So, liberally commenting your scripts can make it much easier to understand what the heck you were doing when you go in and try to make changes to them a few weeks later. Note also that there is no requirement that the entire script definition all be on the same line. Of noteworthy interest also is the fact that you must manually insert the [enter] tags in a special character script (but not in a Simple Text Script).

Other directive tags include the [^str] and [paste] tags. These tags tell WinKeySim to either copy to the clipboard or paste from the clipboard. For example, ["[^Copy this text]"] would put "Copy this text" (without the quotes) to the clipboard. You could then paste the information into your target application at your leisure. The [paste] directive is there more for completeness than anything else. The [paste] tag merely sends a ctrl+v sequence to the target application. The [^str] tag is useful where you want to paste information into an application manually after WinKeySim finishes doing its thing.

Chaining Multiple Items Together

There might be times when you wish to chain one or more items together. You can accomplish this by checking the check box at the bottom of the Edit SubMenus dialog box. When you invoke the top item in the chain, WinKeySim will automatically invoke the rest of the chained items below that one. For example, sometimes your web browser will store your username into a cookie on your hard drive whenever you login to a website, such as hotmail or netscape webmail. So, there are times when you will need to type in both the username and the password and other times when you will only need to enter the password. You could chain two (2) menu items together, the first item being the username and the second item being the password. Then, if you only need the password, you can select the password item, but if you need both the username and the password, you can get both by selecting the username. In such cases, WinKeySim will automatically invoke the password item for you.

Another potential use for the chaining feature is where you wish to have simple text pasted into an application, followed by special character scripting, perhaps followed by more simple text. For example, you might wish to have a script that will automatically type in your address, followed by the current date (CTRL+D, I believe) in MS Word.

Tips

Save your menu item definitions into a .wky file and put a link to this file in your StartUp menu. Each time you restart Windows, WinKeySim will load in the .wky file and position itself ready for duty in the System Tray. WinKeySim is a convenience program. If you are forced to hunt and peck through the Start, Programs, WinKeySim, WinKeySim, File, Open, yourfile.wky, every time you need to login to check your e-mail, you might as well just type in your login manually. On the other hand, if WinKeySim is already there and ready for you, you will be more inclined to take advantage of it. Put a shortcut to yourfile.wky by right-clicking the Start button, Explore, Programs, StartUp, right-click in the right-hand window pane, choose New, Shortcut, Browse, navigate to yourfile.wky.

Place only the menu item definitions you use most often into the special SubMenu named "TopLevel". Too many items in a particular SubMenu will make it less convenient for you to find them when you need them.

Use WinKeySim to create shortcuts to launch programs that you use most often. One easy way to do this is to create a script definition that utilizes the Start button's Run Item. For example, this script would execute the Windows Calculator program: ["rcalc[enter]"] To use it, click the Start button after selecting this item from the context menu. The 'r' brings up the Run dialog, which is then filled in with "calc", followed by the [enter] key which executes the Run command line ("calc"). Similarly, ["rmspaint[enter]"] would execute the Microsoft Paint program. Use ["rnotepad[enter]"] for a script to execute the Notepad.exe program. This can be especially useful where an often-used program, such as notepad is buried several layers deep in the Start Menu heirarchy.

You can create a script definition to open up a folder, such as your c:\windows\cookies folder:

["rc:\windows\cookies[enter]"]

You can also, of course, perform operations upon that folder after it opens, such as deleting all of your cookies:

["rc:\windows\cookies[enter][!2000]i[alt]e[alt_up]i[delete]y"]

That seems like a lot to digest, so let's break it down. The ["rc:\windows\cookies[enter] part opens up the c:\windows\cookies folder. The [!2000] tells WinKeySim to sleep for 2000 milliseconds (2 seconds) while Windows brings up the cookies folder. The "i" selects a file named "index.dat" that cannot be deleted because it is usually in use by the system. The [alt]e[alt_up]i sequence opens the Invert menu item in the Edit Menu in Explorer. The effect is that all files are selected for deletion except the "index.dat" file. The [delete]y sequence deletes all the selected files and confirms deletion with the "y" key, which selects "yes" in the confirmation popup message box. Most of the time, cookies either begin with an "a", such as anyuser@whatever.com or they begin with the first letter in your username. My username is "mwganson". If yours begins with an "i", such as isaacwilliams@whatever.com, this script might not work for you since the "i" will probably just select the first cookie beginning with the letter "i". The work-around would be to first delete all the files that you can by using CTRL+a to select all files. It will fail when attemption to delete the "index.dat" file, but that's okay because you can then use the "i" trick since "index.dat" will then be the first available file beginning with the letter "i".

Here is a script to clear out the history folder in IE5:

["[alt]t[alt_up]o[!1000][alt]h[alt_up][!1000][left][!500][enter]"]

This opens the Tools Menu, Options, Delete History, items. To use it, you must have IE5 open and ready for input. Select the Clear History script and click the IE5 title bar.

If your script doesn't seem to be performing correctly and you are hearing a series of beeps as it runs, it probably means that you need to add a few sleep [!nnn] tags into the script in order to give the computer enough time to complete a task before sending more simulated keystrokes into the keyboard buffer. Insert the sleep tags liberally until you get the script to work properly. You can always go back in and trim them out later.

WinKeySim was not designed to work with DOS programs, but you can simulate keystrokes into a DOS Prompt window by using the Simple Script Method to copy data to the Clipboard. Then, click the DOS Prompt Window title bar and then the Paste button in the DOS Prompt Window's toolbar to paste the data into the window. For example, here is a script to bring up a directory listing of all .exe files in wide format:

dir *.exe /w

Note that this script will exhibit the behavior of a special character script, but does not require the ["..."] syntax. (Be sure to click the DOS Prompt Window's title bar first to insert the script text into the Clipboard, replacing any previous Clipboard contents, before clicking the Paste button. Otherwise, Windows will paste the existing Clipboard contents before allowing WinKeySim to place the script definition there.) If you are pasting into a DOS application, such as the DOS Edit program, click on the desired insertion point for the keystrokes first, then click the Paste button.

If you include an ampersand (&) in the name of your SubMenu/Item, the character following the ampersand will be underlined and interpreted as a keyboard shortcut by the system. WinKeySim supports up to fifty (50) SubMenus and each SubMenu can have as many as fifty (50) items. The more cluttered the context menu becomes, the more difficult it can be to find your desired selection. Also, depending on your screen resolution settings, some of your menu items will be scrolled off the screen at some point when you have too many menu items to fit on the screen at one time. However, if you know the keyboard shortcut, you can go immediately to your selection by pressing the shortcut key. For example, if you have a SubMenu named "e-mail addresses", you could rename it to "e-&mail addresses" to create a shortcut key (m) to it. Then, you will be able to bring up that SubMenu by pressing the 'm' key while the context menu is active. The same thing works with the items contained within a SubMenu as long as that SubMenu is the active SubMenu.

Double-click on the WinKeySim System Tray Icon to bring up the WinKeySim main application window, which is hidden by default. If you have access to the Internet, there are some banner links there to some of my other websites. There is also a link there (at the time of this writing: August, 2000) that will give you a free chance to win a cool $5,000,000.00! (This is a link to my sponsor, which might change at some point in the future, but will always point to a promotion that offers the free chance to win some money, though it might not always be as much as $5,000,000.00.)

Some of my other websites include:

PowerballPicker
NFLPicker
Mark's Adding Machine (freeware)
Java4Free (free java web tools for webmasters)

Visit the WinKeySim Website to check for the latest version periodically and for the latest bug fixes, tips, etc.

Your questions/comments/suggestions/complaints are always welcome. E-mail the author directly at winkeysim@bigfoot.com