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. $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 withinWaitForImage
, the latter can also treat $SUBIMAGE as array of images. - WaitForImage $SUBIMAGE, %OPTIONS
-
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.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.Returns a hash reference, which contains
ok
boolean success flag,x
andy
coordinated and an optionalidx
image index (see third value inFindImage
). Also,grab
in the hash points to the last analyzed screenshot. - 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>