Help Page

'X'

Quick Command Reference

[ClipGet] [ClipPut] [DetectHiddenText] [IfWinActive] [IfWinExist] [IniRead] [IniWrite] [LeftClick] [LeftClickDrag] [MouseGetPosX] [MouseGetPosY] [MouseMove] [RightClick] [RightClickDrag] [Send] [Shutdown] [Sleep] [SetKeyDelay] [SetTitleMatchMode] [SetWinDelay] [WinKill] [WinWait] [WinWaitClose] [WinWaitActive] [WinWaitNotActive] [WinHide] [WinShow] [WinRestore] [WinMinimize] [WinMaximize] [WinActivate] [WinClose] [WinMinimizeAll] [WinMove] [WinSetTitle] [WinGetActiveTitle]

Table of Contents

1. Introduction

2. Intended Use

3. License

4. Year 2000 Statement

5. Using AutoItX

6. Window Titles and Window Text

7. AutoItX Methods

8. Send Method Syntax

9. Examples

10. AutoItX History

Introduction

AutoItX is an ActiveX control version of AutoIt. It allows you to perform the following types of functions:

Sending keystrokes and mouse clicks (all characters, keyboard layout independent).
Window functions (e.g. minimizing, hiding, restoring, waiting for, activating (even under Win98/NT2000)).
Sleep (for those with WSH 1.0 :) )
INI file reading and writing.
Simple clipboard (text) commands.
Shutdown and reboot commands (including a forced reboot that works under both 9x and NT).

Best of all, its small and FREE!

All examples are in WSH-VBScript, although it should work fine from any language capable of using ActiveX components.

Back to Contents

Intended Use

AutoItX is intended to be used to conjunction with other scripting languages such as WSH, VBScript, etc. To "fill in the gaps" of the built in automation routines. If you don't want to use another scripting language, you could try the full version of AutoIt which has it's own .exe and script processing functions.

Back to Contents

License

See License.txt included in this archive.

Back to Contents

Year 2000 Statement

AutoItX uses no date functions, and therefore, to the best of the authors knowledge, is Y2K compliant. However, see the license for standard disclaimers.

Back to Contents

Using AutoItX

AutoItX is an ActiveX control, before use it must be registered on the client machine using "regsvr32.exe". It can then be accessed from the script of your choice (all examples in this archive will use VBScript) (Note, if you installed the full version of AutoIt, the control should already have been registered for you).

To create the AutoItX object you will need the following (or similar) line of code, "AutoItX.Control" is the class name:

Set oAutoIt = CreateObject("AutoItX.Control")

Back to Contents

Window Titles and Text

A number of methods have "Window Title" and "Window Text" as parameters.
"Window Title" is text that appears in the windows title bar.
"Window Text" is any other text on that window, e.g. text on buttons such as "OK" and "Cancel".

Having "Window Text" allows you to distinguish between multiple windows that have the same title.

Neither the title nor text needs to be completely specified.
i.e. "Untitled - No" will match a window with the title "Untitled - Notepad".
See the text on the SetTitleMatchMode method for additions to this.

Use the "/reveal" mode in the full version of AutoIt to see what text is present on a window.

N.B. Windows titles and text are CASE SENSITIVE!!!!!

Back to Contents

AutoItX Methods

The following methods are currently implemented.

Send <Series of key presses>

Sends a set of keystrokes to the currently active window. (The syntax of these keystrokes can be found in the following section).

e.g
Set oAutoIt = CreateObject("AutoItX.Control")
oAutoIt.Send "Hello, this is a line of text"

WinWait <Window Title>, <Window Text> [,<Timeout>]

The WinWait group of methods (WinWait, WinWaitActive, etc.) now feature a Timeout value. This is an optional parameter, and if specified, the function will return after <Timeout> seconds whether or not the function was successful. If successful the function will return 0, if the function timed out it will return 1. The maximum value of Timeout is 32767 seconds.

Stops script execution until the specified window exists. The window does not need be active.

e.g.
Set oAutoIt = CreateObject("AutoItX.Control")
oAutoIt.WinWait "Untitled - Notepad", ""

e.g. This will return "1" if the notepad window does not exist after 5 seconds
Set oAutoIt = CreateObject("AutoItX.Control")
nErr = oAutoIt.WinWait ("Untitled - Notepad", "", 5)

WinWaitClose <Window Title>,<Window Text> [,<Timeout>]

Stops script execution until the specified window ceases to exist.

e.g.
Set oAutoIt = CreateObject("AutoItX.Control")
oAutoIt.WinWaitClose, "Untitled - Notepad", ""

WinWaitActive <Window Title>,<Window Text> [,<Timeout>]

Stops script execution until the specified window to exists and is active.

WinWaitNotActive <Window Title>, <Window Text> [,<Timeout>]

Stops script execution until the specified window ceases to be active.

WinHide <Window Title>, <Window Text>
WinShow <Window Title>, <Window Text>
WinRestore <Window Title>, <Window Text>
WinMinimize <Window Title>, <Window Text>
WinMaximize <Window Title>, <Window Text>
WinActivate <Window Title>, <Window Text>
WinClose <Window Title>, <Window Text>

If the window exists, the relevant command (i.e. miniminzing, hiding, activating, etc.) will be performed.

>> N.B. WinActivate will bring a window to the top even under Win98/NT2000. <<

Sleep <milliseconds>

Halts execution of the script for the given number of milliseconds.
1000 milliseconds = 1 second.

e.g.
Set oAutoIt = CreateObject("AutoItX.Control")
oAutoIt.Sleep 5000

SetKeyDelay <milliseconds>

Changes the delay between sending keystrokes in milliseconds.
Default is 10ms. 1000 milliseconds = 1 second.

e.g.
Set oAutoIt = CreateObject("AutoItX.Control")
oAutoIt.SetKeyDelay 50

LeftClick <x>, <y>
RightClick <x>, <y>

Simulates a left or right mouse button click. The X and Y co-ordinates are relative to the currently active window. Run AutoIt in reveal mode to determine the required co-ordinates of a window. Use the full version of AutoIt to work out what the coordinates are!
To perform a double-click, simply run the command twice :)

e.g.
Set oAutoIt = CreateObject("AutoItX.Control")
oAutoIt.LeftClick 50, 100

SetTitleMatchMode <mode>

Changes the way that window titles are matched against the script.
Valid modes are "1" and "2" - the default is "1". This mode affects most of the commands within AutoIt that have any sort of window title and text in the command, i.e. WinWait, WinWaitActive, IfWinActive, etc.

e.g.
Set oAutoIt = CreateObject("AutoItX.Control")
oAutoIt.SetTitleMatchMode 2

mode 1

In the script you specify the start of a window title to match. i.e. for the notepad.exe window (Untitled - Notepad), valid matches would be:
"Untitled", "Untitled -", "Unt" and "Untitled - Notepad".

mode 2

In the script you can specify ANY substring of the window title you want to match. Again for the notepad.exe window valid matches would be:
"Untitled", "Untitled - Notepad", "Notepad", "No".

WinMove <Window Title>, <Window Text>, <X>, <Y>, <Width>, <Height>

If the window in Title and Text exists, it is moved to <X>, <Y> and resized to <Width>, <Height>

Set oAutoIt = CreateObject("AutoItX.Control")
oAutoIt.WinMove "Untitled - Notepad", "", 0, 0, 100, 100

This moves the notepad window to 0,0 and changes the size of the window to 100,100

WinSetTitle <Window Title>, <Window Text>, <New Title>

Use this method to rename a window.

e.g.
Set oAutoIt = CreateObject("AutoItX.Control")
oAutoIt.WinSetTitle "Untitled - Notepad", "", "new title this is..."

DetectHiddenText <on | off>

Some programs use hidden text on windows (e.g. Backup Exec) this can cause problems when trying to script them. This command allows you to tell AutoIt whether or not to detect this hidden text. Default is "off".

e.g.
Set oAutoIt = CreateObject("AutoItX.Control")
oAutoIt.DetectHiddenText "ON"

<Result> = WinGetActiveTitle

This method gets the title of the active window and puts it in the variable <Result>

e.g.
Set oAutoIt = CreateObject("AutoItX.Control")
CurrentTitle = oAutoIt.WinGetActiveTitle

SetWinDelay <Milliseconds>

This changes the time that AutoIt pauses after carrying out a window related function (waiting for, minimizing, restoring, etc.) before continuing. This is useful on very slow machines, or when you have things like window animation enabled. The default is 500 milliseconds.

e.g.
Set oAutoIt = CreateObject("AutoItX.Control")
oAutoIt.SetWinDelay 2000
oAutoIt.WinWaitActive "Untitled - Notepad", ""
oAutoIt.Send "Hello"

In this example there would be a pause of 2000 milliseconds (2 seconds) after notepad has started until the words "Hello" appear.

WinMinimizeAll

Simply, this method minimizes all windows.

LeftClickDrag <x1>, <y1>, <x2>, <y2>
RightClickDrag <x1>, <y1>, <x2>, <y2>

Drags the mouse pointer from x1,y1 to x2,y2 with the relevant mousebutton held down. The co-ordinates are relative to the current active window.

<Result> = IfWinActive <Window Title>, <Window Text>

This method returns 1 if the window is active, otherwise it returns 0.

e.g.
Set oAutoIt = CreateObject("AutoItX.Control")
nActive = oAutoIt.IfWinActive ("Untitled - Notepad", "")

<Result> = IfWinExist <Window Title>, <Window Text>

This method returns 1 if the window exists, otherwise it returns 0.

e.g.
Set oAutoIt = CreateObject("AutoItX.Control")
nExist = oAutoIt.IfWinExist ("Untitled - Notepad", "")

<Result> = IniRead <Filename>, <Section>, <Key>
IniWrite <Filename>, <Section>, <Key>, <Value>

Allows reading and writing of standard windows .ini files., i.e. the following format.

[SectionName]
KeyName=Value

e.g. To read the value of "mykey" from the "mysection" part of an ini file:
Set oAutoIt = CreateObject("AutoItX.Control")
Value = oAutoIt.IniRead ("c:\path\file.ini", "mysection", "mykey")

e.g. To write the text "womble" into the same section and key:
Set oAutoIt = CreateObject("AutoItX.Control")
oAutoIt.IniWrite ("c:\path\file.ini", "mysection", "mykey", "womble")

NB. The full path and filename of the .ini file must be given.

<Result> = ClipGet
ClipPut <Text>

Allows sending and receiving of up to 8192 characters of text between the clipboard and AutoIt.

e.g. To get text from the clipboard:
Set oAutoIt = CreateObject("AutoItX.Control")
Text = oAutoIt.ClipGet()

e.g. To send the text "Paste Me!" to the clipboard:
Set oAutoIt = CreateObject("AutoItX.Control")
oAutoIt.ClipPut "Paste Me!"

Shutdown <Flag>

This method allow you to perform various forms of shutdown. The type is determined by <Flag>. The flag can be a combination from the table below:

*Function*	*Flag*
Log off the current user	0
Shutdown the workstation	1
Reboot the workstation	2
Force closing of applications (may lose unsaved work)	4
Shutdown and power off (if supported)	8

e.g. To shutdown and force applications to close without saving = Shutdown + Force = 1 + 4 = 5:
Set oAutoIt = CreateObject("AutoItX.Control")
oAutoIt.Shutdown 5

WinKill <Window Title>, <Window Text>

Similar to WinClose, but if the window has not closed after a couple of seconds (Asking to save, crashed, etc.) the window will be forcibly terminated.

<Result> = MouseGetPosX
<Result> = MouseGetPosY

This method will get the current position of the mouse cursor into the 'x' and 'y' variables. The co-ords are relative to the active window.

e.g.
Set oAutoIt = CreateObject("AutoItX.Control")
xPos = MouseGetPosX()
yPos = MouseGetPosY()

MouseMove <x pos>, <y pos>

This method will move the mouse cursor to the position <xpos>, <ypos>. The co-ords are relative to the active window.

e.g.
Set oAutoIt = CreateObject("AutoItX.Control")
MouseMove 10, 100

Back to Contents

"Send" Command Syntax

The "Send" command syntax is similar to that of ScriptIt and the Visual Basic "SendKeys" command. Characters are sent as written with the exception of the following characters:

'!'
This tells AutoIt to send an ALT keystroke, therefore "Send,This is text!a" would send the keys "This is text" and then press "ALT+a".

N.B. Some programs are very choosy about capital letters and ALT keys, i.e. "!A" is different to "!a". The first says ALT+SHIFT+A, the second is ALT+a. If in doubt, use lowercase!

'+'
This tells AutoIt to send a SHIFT keystroke, therefore "Send,Hell+o" would send the text "HellO". "Send,!+a" would send "ALT+SHIFT+a".

'^'
This tells AutoIt to send a CONTROL keystroke, therefore "Send,^!a" would send "CTRL+ALT+a".

N.B. Some programs are very choosy about capital letters and CTRL keys, i.e. "^A" is different to "^a". The first says CTRL+SHIFT+A, the second is CTRL+a. If in doubt, use lowercase!

'#'
The hash is used as a key delimiter to make a line easier to read. i.e. "Send, H#e#l#l#o" is the same as "Send,Hello".

Certain special keys can be sent and should be enclosed in braces:

N.B. Windows does not allow the simulation of the "CTRL-ALT-DEL" combination!

Send Command	Resulting Keypress
{!}	!
{#}	#
{+}	+
{^}	^
{{}	{
{}}	}
{SPACE}	SPACE
{ENTER}	ENTER
{ALT}	ALT
{BACKSPACE} or {BS}	BACKSPACE
{DELETE} or {DEL}	DELETE
{UP}	Cursor up
{DOWN}	Cursor down
{LEFT}	Cursor left
{RIGHT}	Cursor right
{HOME}	HOME
{END}	END
{ESCAPE} or {ESC}	ESCAPE
{INSERT} or {INS}	INS
{PGUP}	PGUP
{PGDN}	PGDN
{F1} - {F12}	Function keys
{TAB}	TAB
{PRINTSCREEN}	PRINTSCR
{LWIN}	Left Windows key
{RWIN}	Right Windows key
{NUMLOCK}	NUMLOCK
{CTRLBREAK}	Ctrl+break
{PAUSE}	PAUSE
{CAPSLOCK}	CAPSLOCK
{NUMPAD0} - {NUMPAD 9}	Numpad digits
{NUMPADMULT}	Numpad Multiply
{NUMPADADD}	Numpad Add
{NUMPADSUB}	Numpad Subtract
{NUMPADDIV}	Numpad Divide
{NUMPADDOT}	Numpad period
{APPSKEY}	Windows App key
{ALTDOWN}	Holds the ALT key down until {ALTUP} is sent
{SHIFTDOWN}	Holds the SHIFT key down until {SHIFTUP} is sent
{CTRLDOWN}	Holds the CTRL key down until {CTRLUP} is sent
{ASC nnnn}	Send the ALT+nnnn key combination

To send the ASCII value A (same as pressing ALT+65 on the numeric keypad)
    Send, {ASC 65}

Single keys can also be repeated, e.g.
    Send, {DEL 4}    Presses the DEL key 4 times
    Send, {S 30}       Sends 30 'S' characters
    Send, +{TAB 4} Presses SHIFT+TAB 4 times

Back to Contents

Examples

Some US English examples are included with this archive, others can be found on the AutoIt home page.

Back to Contents

AutoItX History

20/12/99 - v1.32

Internal changes and optimizations.

10/12/99 - v1.3

MouseGetPosX and MouseGetPosY methods added.
MouseMove method added.
Bugs with sending keystrokes to DOS fixed.

25/11/99 - v1.23

WinActivate tweaked for Win2000 RC2.
Shutdown command added.
WinKill command added.

23/11/99 - v1.22

Simple clipboard commands added.
INI file commands added.

20/11/99 - v1.21

Can now Send decimal ASCII codes, like when using using the ALT key and the numeric keypad (e.g. ALT+65 = 'A'). Very useful for sending characters that don't usually work (e.g. '~' on an Italian keyboard).

18/11/99 - v1.2

Added methods IfWinActive, IfWinExist and WinShow
Added timeout functionality to the WinWait group of methods

11/09/99 - v1.1

Fixed "processor hog" bug in WinWaitActive.
Added keys {CTRLUP}, {CTRLDOWN}, {SHIFTUP}, {SHIFTDOWN}, {ALTUP}, {ALTDOWN}.

28/08/99 - v1.01

Added methods LeftClickDrag and RightClickDrag.

19/08/99 - v1.0

First version

Back to Contents