NAME

Win32::GUIRobot - send keyboard and mouse input to win32, analyze graphical output

DESCRIPTION

The module is a superset of Win32::GuiTest module functionality, with addition of simple analysis of graphic output. The module is useful where analysis based on enumeration of window by title, class, etc is not enough (in particular in Citrix environment), by providing searching of arbitrary graphic bits on the screen.

The module is a mixed bag of various win32 functions with the same purpose as Win32::GuiTest - to provide environment for batch windows GUI tests/macros, but also focusing on code logic reuse when many similar GUI scripts should be written. Therefore, in addition to image search, the module also features a set of wrapper functions to win32 API, timers, etc.

IMAGING

Image operations, -- loading, retrieving information etc is based on Prima, which can work not only on win32, so the module can be of limited use on X11, for searching sub-images in images and grabbing the screen. Possibly this functionality is worth releasing as a stand-alone module, but OTOH the image search is not limited to Prima toolkit, and can be trivially implemented using any other image system, not to say that the searching algorithm itself is very simple, and being abstracted from image toolkit calls, is a single regexp.

Functions collected below are little more than aliases to Prima methods, but for the sake of consistency, and in case Prima will be replaced by some other toolkit, image methods are replaced by opaque method wrappers:

ScreenDepth

Returns image depth of a screen dump.

ScreenWidth

Returns screen width

ScreenHeight

Returns screen height

LoadImage $FILENAME

Loads image from $FILENAME, returns image object.

ScreenGrab [ $X, $Y, $WIDTH, $HEIGHT ].

Grabs the screen, returns image object with the screen dump. If no parameters given, grabs the whole screen, otherwise the area limited by the passed coordinates.

ImageDepth $IMAGE

Returns $IMAGE color depth

ImageWidth $IMAGE

Returns $IMAGE width

ImageHeight $IMAGE

Returns $IMAGE height

FindImage $IMAGE, $SUBIMAGE

Searches position of $SUBIMAGE in $IMAGE, reports coordinate if found, empty list otherwise.

WaitForImage $SUBIMAGE, $MAXWAIT, $SLEEP, [ $X, $Y, $WIDTH, $HEIGHT ]

Monitors area given by $X,$Y,$WIDTH,$HEIGHT on the screen ( or the whole screen if coordinates are not given) for $SUBIMAGE to appear. Takes screenshots every $SLEEP seconds. Return either empty list when $MAXWAIT expires, or (x,y) coordinates where $SUBIMAGE was found otherwise.

Rect2OffsetSize $LEFT, $TOP, $RIGHT, $BOTTOM

Converts win32 RECT(left,top,right,bottom) into OffsetSize(left,top,width,height). Useful for constructions like

$grab = ScreenGrab( Rect2OffsetSize( GetWindowRect( $HWND)));

OTHER FUNCTIONS

Sleep [ $SECONDS = DEFAULT_SECONDS ]

Sleeps given amount of seconds, or 0.02 by default.

SendMouseClick $BUTTON, $X, $Y, [ $SLEEP_BETWEEN_EVENTS ]

Positions mouse cursor over $X, $Y, sleeps some time, then sends button down event, sleeps again, then button up event and sleeps again.

MouseMove $X, $Y

Moves mouse cursor to $X, $Y

MouseMoveRel $X, $Y

Moves mouse cursor to $X, $Y relatively to the old cursor position

CloseWindow $HWND

Sends close signal to a window.

BUGS

I didn't try image search on 8-bit paletted displays -- beware.

Prima coordinates ( images included ) is defined so Y axis grows upwards, whereas in win32 screen coordinates, Y axis grows downwards. The wrapper methods take care of the coordinate conversion, however if you need to call Prima methods, beware of this difference.

SEE ALSO

Prima, Win32::GuiTest, Win32::Capture, Win32::Snapshot, Win32::GUI::DIBitmap.

LICENSE AND COPYRIGHT

Copyright (c) 2007 capmon ApS. All rights reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

AUTHOR

Dmitry Karasik <dmitry@karasik.eu.org>