The ClipRectangle property of an image was introduced in Eggplant 3.0 to provide a mechanism for trimming an image at search time in order to look for a smaller, “clipped” version of that image. This was intended mainly to provide a fallback means of dealing with text images that might need to be trimmed in some special cases, such as to find text that might be underlined in a different way than underlined text images are generated (we’ve found that underlining is not always done in a consistent way by different applications, so sometimes ignoring the underline may be the only way to get generated text images to match).
Because text images were new at the time, and the clipRectangle property was a potentially confusing approach to a problem that we hoped not many people would run into, it wasn’t initially included in the documentation (although it shows up briefly in the release notes!). I expect we will document it properly in the future, but for the moment, here’s a brief description of how to use it.
First, here’s what it says in the release notes: “Image property lists may now include a ClipRectangle property. If present, its value should be a rectangle. The image will be clipped to the intersection of this rectangle with the image’s rectangle before searching.”
The most likely way to use this is to adjust from the original size of the image. Each image has a size (width and height) that can be found by accessing the ImageSize property of the image property list returned by the ImageInfo() function:
set imageSize to ImageInfo("MyImage").ImageSize
You can then use this size to calculate a ClipRectangle that will trim off part of the image. For example, to trim 2 pixels off the bottom (keeping in mind that the coordinate origin in Eggplant is at the top left) you might do this:
set clipRect to (0, 0, imageSize.width, imageSize.height-2)
click (ImageName:"MyImage", ClipRectangle:clipRect)
To keep the example simple I used a named image above. But of course ClipRectangle can be used with text images, too.
click (Text:"File", TextStyle:"WindowsMenu", ClipRectangle:clipRect)
Hopefully this explanation is enough to make the ClipRectangle property useful. Happy clipping!