[eggPlant Functional] Restricting the search area

Sometimes the thing that you want to find on the screen shows up in more than one place – maybe there are two “okay” buttons visible, or a menu and dropdown list have the same label. In those cases, you may want to restrict the area of the screen that Eggplant searches so that it only finds the instance of the image that you want.

Eggplant has always allowed you to restrict the area of the screen that is searched for an image using code of the form:

set the SearchRectangle to ( x,y,x,y )

but that approach can be tricky, especially if you forget that you set the search rectangle and are wondering why Eggplant isn’t finding something that you can see on the screen.

In Eggplant 1.5, we introduced the ability to specify the searchRectangle as part of the image property list passed to a command. So, for example, you might type something like this:

Click ( imageName: "myImage", searchRectangle: ( 0, 0, 200, 200 ) )

This says that you want Eggplant to click “myImage” only if it appears in a square area that starts at the upperleft corner of the remote screen and extends 200 pixels down and 200 pixels to the right. This restriction is in effect only for this Click command, and you don’t need to do anything to make Eggplant search the whole screen on subsequent commands.

To make this process even easier, I’ve created a helper suite that contains scripts for the following functions:

InRectangle( image1, image2 )
ToTheRightOf( imageName )
ToTheLeftOf( imageName )
Above( imageName )
Below( imageName )
BetweenHorizontally( image1, image2 )
BetweenVertically( image1, image2 )
LeftOfAndAbove( imageName )
LeftOfAndBelow( imageName )
RightOfAndAbove( imageName )
RightOfAndBelow( imageName )
AboveAndToTheLeftOf( imageName ) // alias of LeftOfAndAbove
BelowAndToTheLeftOf( imageName ) // alias of LeftOfAndBelow
AboveAndToTheRightOf( imageName ) // alias of RightOfAndAbove
BelowAndToTheRightOf( imageName ) // alias of RightOfAndBelow

Using these functions allows you to easily specify the area of the screen that you want to search based on one or two known image locations. These functions can be used either by setting the SearchRectangle or with the property list argument syntax, for example:

set the SearchRectangle to LeftOfAndBelow( "ModePopUp" )

Click ( imageName: "OkayButton", searchRectangle: BetweenHorizontally( "TitleBar", "ResizeControl" ) )

DoubleClick ( imageName: "myIcon", searchRectangle: Above( "myOtherIcon" ) )

To use this suite, download it, unzip it, and add it as a Helper suite to any suite that you want to have access to these functions.

can you combine those functions (like below, above) with ReadText function? if yes, please show any example

any update to this?

Sure. Each of the functions returns a rectangle, so you can say things like:

put readText(BelowAndToTheLeftOf("someImage")
Click (text:"some string", searchRectangle:BetweenHorizontally("image1", "image2"))