WinSendKeys 3.0.2 Readme.txt
---------------------------------------------------------------------
Author: Ath
Date: 2011-04-22
Version: 3.0.4.0
Updates:
Support: www.donationcoder.com/forum/index.php?topic=25389.0
History:
Removed, read all in the WinSendKeys.au3 sourcefile
---------------------------------------------------------------------

Use-case:
Split_e, user at the DonationCoder.com forum, needed a tool to flip the pages of his e-book reader software, after shooting a screen using ScreenShotCaptor.
That tool wasn't easily found on the internet, but scripting tools like AutoIt3 and AutoHotKey can easily do that, so it's a nice challenge to bring them together :)
Then WinSendKeys 1.0 was born, created using AutoIt3 (www.autoitscript.com/autoit3) because I have some experience in it. It took me about an hour, including testing, to create it, and parsing a few command-parameters so it's a little manageble.
The next, yet unnumbered, release included debug-logging, and a few small improvements.
After the release, Split_e explained what and how he was using it, and that the e-reader he's using wasn't keyboard-controlable any longer, so he added another AHK script to press a button in the interface.
But that mouse-press/control-clicking can ofcourse also be done by AutoIt3, so I decided to add that as a feature to WinSendKeys. After fiddling around a few hours, interpreting the sometimes sparse AutoIt3 documentation, it's now also controling the mouse and where it clicks.
I decided to name this version 2.0, because of the rather major enhancement.
Next was the promissed feature of reading strokes from a file, and that was added in version 2.5
Version 2.6 added ClipBoard content handling
Version 3.0 can optionally start an executable file (with parameters) if the WindowName is not found or executablename is not running yet
A few settings are read from WinSendKeys.ini, if that file exists.

Below is an explanation of how to use all of WinSendKeys' features.

Todo/Planned for a next release:
- Any requests?

Usage:
The general use is to let WinSendKeys send keystrokes to an application you need to control 'from the outside' and without direct user-interaction.
Commands can be placed as parameters on the command-line or in a specified textfile, one stroke per line.

Syntax:
WinSendKeys [-d] [-t keydelay] [-m|-mm speed] [-c|-cc] [-cn] [-x executable_filepath] [-xp executable_parameters] [-w] [<WindowName>] [<KeyStrokes/MouseStrokes>] [...]
Options: (anything between [] is optional)
-d :			Enable debug mode, writing log information to WinSendKeys.log (or whatever the tool is renamed to), and displays a messagebox if the window isn't found.
-t keydelay :	Change the delay between separate KeyStrokes/MouseStrokes. Value in milliseconds. Default is 100 msec.
-m :			Enable MouseStrokes mode. Speed = 0, moves the mousecursor immediately, without animation.
-mm speed :		Enable MouseStrokes mode with mouse moving with <speed> from it's current position to the new position. Valid range: 1 (fast) to 100 (slow). Out of range sets speed to 0.
-f strokefile :	Read KeyStrokes and/or MouseStrokes from this file, line by line, keydelay is applied after each line. Comments have a semicolon in the first position, empty lines are ignored. Command-line strokes are handled first.
-c :			Send any text-content of the Windows Clipboard to the WindowName selected.
-cn :			Like -c option, but does not send an {ENTER} after each line/command, can be added after -c or -cn to disable the {Enter} being sent
-cc :			Like -c option, but the clipboard content can be embedded at the commandline using #$ prefix, like #$* to send all clipboard content, equal to -c option, #$ or #$0 to send the next line available, stops after the last line, 
				or #$3 to send 3rd line from the clipboard (1-based) if that exists, #$3 #$ sends line 3 and 4 from the clipboard
-x executable_filepath :	Specify an executable to start if WindowName is not found. If no WindowName is specified, the executable is searched first, and executed if not found. Surround with quotes if the path has any spaces.
-xp executable_parameters :	Any parameters to pass onto executable_filepath, if the parameters need spaces, use quotes to group the parameters into 1 piece.
-xd delay :		Delay for <delay> millisecondes after running -x executable_filepath, to allow for starting & initializing that app. It is added to the -t delay (100 msec) that was already there. Default = 0.
-? :			Display the help message on screen.
-w WindowName :	Select (bring to foreground) an active, visible, application with this name/title. Exact rules/format documented here: www.autoitscript.com/autoit3/docs/intro/windowsadvanced.htm
                So WindowName kan be a partial match, like "- notepad" to select a notepad instance with an open document, or "readme.txt - notepad" to explicitly select that window, or [CLASS:Notepad] to select Windows Notepad.
                Next to specifying an application by title, it can also be selected by naming the Window ClassName, etc. as documented. 
				When passing a numeric value (not hex!) then it will be converted to a Window  Handle (HWnd), for other tools to more easily pass a known window
             -> This rather technical information can best be determined using 'AutoIt Window Info', installed with AutoIt3, as it presents the information in a way that can easily be copy/pasted onto the command-line or into a (batch)script.
                If the window can not be found, no keys are sent, use [ACTIVE] to send keystrokes to the current active window.
                If no KeyStrokes or MouseStrokes are specified, then only the window is activated.
				If WindowName is not specified but -x executable_filepath option is used, then that window is activated.
<KeyStrokes> :	Keystrokes are descriptive keys or normal text, to be sent to the window, just specified. If no keystrokes or mousestrokes are specified, then only the window is brought to front.
				The entire set of keys is documented at the AutoIt3 site: www.autoitscript.com/autoit3/docs/appendix/SendKeys.htm
				Keys can be sent in small or larger groups, depending on requirement and reaction-speed of the application. Keystrokes grouped together are sent as one sequence, when separated by a space, the keydelay is applied, 
				so using {TAB}^^b^^u sends these 3 keystrokes <Tab>, Ctrl-B, Ctrl-U as 1 group, and {TAB} ^^b ^^u sends <Tab>, delay(100 msec), Ctrl-B, delay(100 msec), Ctrl-U, to the application. 
			 -> The ^ character, meaning Ctrl in AutoIt3 speak, NEEDS to be doubled on a Windows commandline, as a single ^ is the escape-character for otherwise special characters in CMD.EXE like >, ( etc.
				If you need to send a space, or want to send multiple the same keystrokes, just wrap it inside single or double quotes, like ' ' for a space ({SPACE} would also work), or "{DOWN 5}" to send 5 times a DownArrow keypress.
			 -> Sending Ctrl or Alt keys is usually best done using lower-case letters, as not all apps support upper-case here or interpret Ctrl-Shift-<Character> differently.
<MouseStrokes> :	MouseStrokes are sets of parameters to either the ControlClick or MouseClick function of AutoIt3. 
					Documentation for ControlClick: www.autoitscript.com/autoit3/docs/functions/ControlClick.htm
					Documentation for MouseClick: www.autoitscript.com/autoit3/docs/functions/MouseClick.htm
					The Control or Mouse clicks are distinguished from KeyStrokes by a prefix, ## for ControlClick, and #% for MouseClick.

ControlClick parameters: ##[<WindowName>],[<Text>],Control[,Button[,Clicks[,x[,y]]]]
WindowName : See WindowName above, defaults to the WindowName parameter given earlier.
Text : Text to select the window, usually empty.
Control :	The ControlID or control description as documented here: www.autoitscript.com/autoit3/docs/intro/controls.htm
			If a numeric ControlID is used, it is changed to [ID:<id>] to ease the use
		 -> This rather technical information can best be determined using 'AutoIt Window Info', installed with AutoIt3, as it presents the information in a way that can easily be copy/pasted onto the command-line, into a (batch)script or strokes file.
Button :	Defaults to "Primary" if not specified, for a standard configuration that's a left-button click, and for a left-handed configured mouse it's a right-button click.
Clicks :	Number of mouse-clicks to send. Defaults to 1.
x,y :		Position of the click to occur. Defaults to the centre of the selected control. If only x is specified, y still gets set to the vertical centre.
Example: 
WinSendKeys -m "Management Console" "##,,[CLASS:TToolBar; INSTANCE:1],,,12,12"
This clicks on a window called Management Console, and presses a key on a toolbar, on coordinate 12,12 within the toolbar, where the Close button is located :-)
The ControlClick is enclosed in quotes because the control specification has a space in it, and that would split this MouseStroke, which isn't supported.

MouseClick parameters: #%Button,x,y[,Clicks[,speed]]
Button :	Defaults to "Primary" if not specified, for a standard configuration that's a left-button click, and for a left-handed configured mouse it's a right-button click.
Clicks :	Number of mouse-clicks to send. Defaults to 1.
x,y :		The position to click relative to the selected Window.
Speed :		The mouse-move speed, defaults to the -mm parameter above, or 0 if not set. Range 0 (immediate), 1 (fast) to 100 (slow)
Example:
WinSendKeys.exe -m "Management Console" #%,20,70
Clicks in the same windows as the ControlClick example, but this time clicks on the relative position of the toolbar button within the window to close the application.

ClipboardStrokes examples
Example 1:
WinSendKeys -cc [ACTIVE] dir{Enter} #$ {Tab}
- This sends a 'dir' command (activated by {Enter}) to the currently active window (a cmd.exe session?), the first line of the clipboard including an {Enter}, and a {Tab} keystroke.
Example 2:
WinSendKeys -c [ACTIVE]
- This sends all lines on the clipboard to the currently active window (a cmd.exe session?), each followed by an {Enter}
