Back to [[.:|Script Function Reference]]

====== Run_Emulator_Send_Keys() ======

The Run_Emulator_Send_Keys() function runs the emulator with any command line arguments that have previously been set using the [[.:add_clp|Add_CLP()]] or [[.:add_clp2|Add_CLP2()]] functions, then sends the specified keystrokes to it.

===== Syntax =====

<code>Run_Emulator_Send_Keys(keystrokes||duration||[DOSCLOSE])</code>

===== Arguments =====

Arguments are separated by the || delimiter.

^ Argument ^ Required ^ Description ^
| //keystrokes// | Yes | Each key is represented by one or more characters. To specify a single keyboard character, use the character itself. For example, to represent the letter A, use "A". To represent more than one character, append each additional character to the one preceding it. To represent the letters A, B, and C, use "ABC".\\ \\ The plus sign (+), caret (%%^%%) and percent sign (%) have special meanings. To specify one of these characters, enclose it within braces ({}). For example, to specify the plus sign, use {+}. To specify brace characters, use {{} and {}}. To specify the GEMUS parameter separator (%%||%%) use {DOUBLEPIPE}. To specify square brackets, use {OPENSQB} and {CLOSESQB}. Any [[..:environment_variables|script environment variables]] found in keystrokes will be replaced by their actual values when the script is executed.\\ \\ To specify characters that aren't displayed when you press a key, such as ENTER or TAB, and keys that represent actions rather than characters, use the codes shown below: \\ \\ ALT: {MENU} or {ALT}\\ BACKSPACE: {BACKSPACE}, {BS}, or {BKSP}\\ BREAK: {BREAK} or {CANCEL}\\ CAPS LOCK: {CAPSLOCK}\\ CLEAR: {CLEAR}\\ CONTROL: {CONTROL}\\ DEL or DELETE: {DELETE} or {DEL}\\ DOWN ARROW: {DOWN}\\ END: {END}\\ ENTER:  {ENTER}\\ ESC: {ESC}, or {ESCAPE}\\ EXECUTE: {EXECUTE}\\ HELP: {HELP}\\ HOME: {HOME}\\ INS or INSERT: {INSERT} or {INS}\\ LEFT ARROW: {LEFT}\\ LEFT MOUSE BUTTON: {LBUTTON}\\ MIDDLE MOUSE BUTTON: {MBUTTON}\\ NUM LOCK: {NUMLOCK}\\ NUMBER PAD 0: {NUMPAD0}\\ NUMBER PAD 1: {NUMPAD1}\\ NUMBER PAD 2: {NUMPAD2}\\ NUMBER PAD 3: {NUMPAD3}\\ NUMBER PAD 4: {NUMPAD4}\\ NUMBER PAD 5: {NUMPAD5}\\ NUMBER PAD 6: {NUMPAD6}\\ NUMBER PAD 7: {NUMPAD7}\\ NUMBER PAD 8: {NUMPAD8}\\ NUMBER PAD 9: {NUMPAD9}\\ NUMBER PAD ADD: {ADD}\\ NUMBER PAD DECIMAL: {DECIMAL}\\ NUMBER PAD DIVIDE: {DIVIDE}\\ NUMBER PAD MULTIPLY: {MULTIPLY}\\ NUMBER PAD SEPARATOR: {SEPARATOR}\\ NUMBER PAD SUBTRACT: {SUBTRACT}\\ PAGE DOWN: {PGDN}\\ PAGE UP: {PGUP}\\ PAUSE: {PAUSE}\\ PRINT SCREEN: {PRTSC}\\ RIGHT ARROW: {RIGHT}\\ RIGHT MOUSE BUTTON: {RBUTTON}\\ SCROLL LOCK: {SCROLLLOCK}\\ SELECT: {SELECT}\\ SHIFT: {SHIFT}\\ SNAPSHOT: {SNAPSHOT}\\ SPACE: {SPACE}\\ TAB: {TAB}\\ UP ARROW: {UP}\\ F1: {F1}\\ F2: {F2}\\ F3: {F3}\\ F4: {F4}\\ F5: {F5}\\ F6: {F6}\\ F7: {F7}\\ F8: {F8}\\ F9: {F9}\\ F10: {F10}\\ F11: {F11}\\ F12: {F12}\\ F13: {F13}\\ F14: {F14}\\ F15: {F15}\\ F16: {F16}\\ Character with ASCII value XXX: {C//XXX//}\\ \\ To specify keys combined with any combination of the SHIFT, CTRL, and ALT keys, precede the key code with one or more of the following codes: \\ \\ SHIFT: + \\ CTRL: %%^%% \\ ALT: % \\ \\ To specify that any combination of SHIFT, CTRL, and ALT should be held down while several other keys are pressed, enclose the code for those keys in braces. For example, to specify to hold down SHIFT while E and C are pressed, use "+{EC}". To specify to hold down SHIFT while E is pressed, followed by C without SHIFT, use "+EC".\\ \\ To specify repeating keys, use the form {key number}. You must put a space between key and number. For example, {LEFT 42} means press the LEFT ARROW key 42 times; {h 10} means press H 10 times.\\ \\ You can tell GEMUS to pause at any time when sending keys by putting the number of seconds within square brackets. "HELLO[5]JIMBO" will tell the function to pause for 5 seconds before sending the text "JIMBO".\\ \\ **Note: You should almost always wait a second or two before sending *any* keystrokes, else they will be sent before the emulator has fully loaded/is ready to receive them. E.g. "[2]HELLO[5]JIMBO" (waits 2 seconds before sending anything).**\\ \\ You can also override the default keypress //duration// (see below) by putting the number of milliseconds duration preceded by a dash ( - ) within square brackets. "HELLO[-20]JIMBO" will tell the function to change the duration to 20ms after the word HELLO has been typed. |


| //duration// | Yes | This is the //default// duration, in milliseconds, to wait both before and during each keystroke. In effect this determines how long to pause between keystrokes and how long a key should be "pressed". Some emulators behave differently when keystrokes are sent to them, for example with WinVICE (tested with v2.1) if there is 0 duration, keystrokes are processed too quickly and are not received by the emulator at all. I found good results using a duration of 100ms, but be wary when using long durations, as the system's key-repeat rate might come into effect (this happened on my system at 400ms). |
| //DOSCLOSE// | No | If the literal string //DOSCLOSE// is supplied as a function argument and the emulator runs in MSDOS mode, the DOS command window will be automatically closed when the emulator closes. You should only supply this parameter if the emulator runs in MSDOS mode. |
\\ 

===== Examples =====

<code>Run_Emulator_Send_Keys([5]run {C34}foo.exe{C34}{ENTER}||100)</code>
Waits 5 seconds, then sends 'run "foo.exe"' and the ENTER key, pausing for 100ms between each keypress, and holding each key down for 100ms. Note the use of {C34} here to represent a quote character ( " ). This is recommended for maximum compatibility across different keyboard layouts.

<code>Run_Emulator_Send_Keys([5]HELLO{ENTER}[-10] JIMBO||100)</code>
Waits 5 seconds, then sends 'HELLO', then the ENTER key, then ' JIMBO'. It starts of with a keypress duration of 100ms, but this is overridden to 10ms before 'JIMBO' is typed (in effect typing it //faster//). 

<code>Run_Emulator_Send_Keys([5]HELLO[10] JJ{BACKSPACE}IMBO||50||DOSCLOSE)</code>
Waits 5 seconds, then sends 'HELLO', then waits 10 seconds, then sends ' JIMBO' (correcting the extra 'J' by sending a BACKSPACE keypress). It pauses for 50ms between each keypress, and each keypress is held down for 50ms. The command/DOS box is then closed when the emulator closes.
\\ \\ 
GEMUS [[..:environment_variables|script environment variables]] are allowed in the //keystrokes// argument. You can also create GEMUS key=value pairs and use those, for example:\\ \\ create a key=value pair:<code>autotype=run +2%gamepathfile%+2{ENTER}</code>then:<code>Run_Emulator_Send_Keys([5]%autotype_value%||100)</code>

===== Remarks =====

  * Specifying ASCII values for certain keystrokes is recommended due to different keyboard layouts. For example, you should use {C34} for a " character for maximum compatibility.
  * Sending keys successfully depends for the most part on the emulator and the way it listens for keystrokes. This GEMUS function uses the Windows API call keybd_event() and should work on most Windows and DOS-based emulators. It may not work if an emulator uses DirectInput to scan for keypresses, as this operates at a much lower level than Windows messages. Basically if it doesn't work, I advise giving up or trying another emulator, or maybe check out [[http://www.autohotkey.com/|AutoHotkey]]. Please also note, the Window must have the focus in order to receive the keyboard events.
  * On some systems, emulators that run in MSDOS mode only allow a command string to be a certain length. If you find that the emulator will not execute, try reducing the length of the command line parameters. A common reason for this is because you have added the game's path to the command line parameters and the path is too long or has too many subfolders. Try moving your game path nearer to the root of it's current drive and ensure that you have selected to use short 8.3 filenames.

===== See Also =====

  * [[.:run_emulator|Run_Emulator()]]
  * [[.:run_gamefile|Run_GameFile()]]
  * [[.:run_program|Run_Program()]]
  * [[.:|Script Function Reference]]