Win32::GUIRobot - send keyboard and mouse input to win32, analyze graphical output
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.
Win32::GuiTest
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.
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.
Prima
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:
Returns image depth of a screen dump.
Returns screen width
Returns screen height
Loads image from $FILENAME, returns image object.
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.
Returns $IMAGE color depth
Returns $IMAGE width
Returns $IMAGE height
Searches position of $SUBIMAGE in $IMAGE, reports coordinate if found, empty list otherwise. $SUBIMAGE can be an array of images, in which case, coordinates of first found image is reported, and the index of the image found is returned as a third value. Since FindImage is called within WaitForImage, the latter can also treat $SUBIMAGE as array of images.
FindImage
WaitForImage
Monitors area on the screen for $SUBIMAGE to appear by taking screenshots every $OPTIONS{sleep} seconds. Fails list when $OPTIONS{maxwait} expires, succeeds and returns (x,y) coordinates where $SUBIMAGE was found otherwise.
$OPTIONS{sleep}
$OPTIONS{maxwait}
The monitored area is can be selected either by specifying $OPTIONS{window} in which case the window area is tracked, or by speciying explicit $OPTIONS{rect} which is a 4-integer (X,Y,WIDTH,HEIGHT) rectangle, or by not specifying anything, in which case the whole screen is monitored.
$OPTIONS{window}
$OPTIONS{rect}
Returns a hash reference, which contains ok boolean success flag, x and y coordinated and an optional idx image index (see third value in FindImage). Also, grab in the hash points to the last analyzed screenshot.
ok
x
y
idx
grab
Converts win32 RECT(left,top,right,bottom) into OffsetSize(left,top,width,height). Useful for constructions like
$grab = ScreenGrab( Rect2OffsetSize( GetWindowRect( $HWND)));
Sleeps given amount of seconds, or 0.02 by default.
Positions mouse cursor over $X, $Y, sleeps some time, then sends button down event, sleeps again, then button up event and sleeps again.
Moves mouse cursor to $X, $Y
Moves mouse cursor to $X, $Y relatively to the old cursor position
Sends close signal to a window.
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.
Prima, Win32::GuiTest, Win32::Capture, Win32::Snapshot, Win32::GUI::DIBitmap.
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.
Dmitry Karasik <dmitry@karasik.eu.org>
To install Win32::GUIRobot, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Win32::GUIRobot
CPAN shell
perl -MCPAN -e shell install Win32::GUIRobot
For more information on module installation, please visit the detailed CPAN module installation guide.