Region

A rectangle on the screen that define the search area

Constructor
Region(x: number = 0, y: number = 0, w: number = 0, h: number = 0)

Construct a Region from its top left cordinate, width and height

Parameters
x The x coordinate of the top left point
y The y coordinate of the top left point
w Width of the region
h Height of the region

Region(region: Region)

Construct a Region from another Region

Parameters
region another Region to copy value from
Constants

LEFT: number = 1

TOP: number = 2

RIGHT: number = 4

BOTTOM: number = 8

Static Methods
deviceReg
static Region deviceReg(padLeftPercent: number = 0, padTopPercent: number = 0, padRightPercent: number = 0, padBottomPercent: number = 0)

Construct a region from the current device's dimensions. noScale is set to true. Optional parameters to pad the region

Parameters
padLeftPercent The left padding in percent
padTopPercent The top padding in percent
padRightPercent The right padding in percent
padBottomPercent The bottom padding in percent
Return
Region The region with dimensions (0, 0, device x, device y)
macroReg
static Region macroReg(padLeftPercent: number = 0, padTopPercent: number = 0, padRightPercent: number = 0, padBottomPercent: number = 0)

Construct a region from the macro's dimensions. noScale is set to false. Optional parameters to pad the region

Parameters
padLeftPercent The left padding in percent
padTopPercent The top padding in percent
padRightPercent The right padding in percent
padBottomPercent The bottom padding in percent
Return
Region The region with dimensions (0, 0, macro x, macro y)
scale
static Region scale(x: number, y: number, w: number, h: number, edges: number = 0)

Scale the region from macro dimension to current device dimension. noScale is set to true. Use edges parameter to specify which edges the region will stick to after scaling

Cutout of the macro device and current device is taken into account. Refer to setMacroCutouts, setDeviceCutouts

Parameters
x The x coordinate of the top left point in macro dimension
y The y coordinate of the top left point in macro dimension
w Width of the region in macro dimension
h Height of the region in macro dimension
edges Edge of the screen to scale the region to. Possible values are Region.LEFT, Region.TOP, Region.RIGHT, Region.BOTTOM. Can be combined for example Region.LEFT + Region.TOP
Return
Region Scaled region in device dimension
highlightOff
static void highlightOff()

Turn off highlight for all regions

Methods
getX
number getX()

Get the x coordinate of the top left point

Return
number The x coordinate of the top left point
getY
number getY()

Get the y coordinate of the top left point

Return
number The y coordinate of the top left point
getW
number getW()

Get the region's width

Return
number The region's width
getH
number getH()

Get the region's height

Return
number The region's height
getMiddlePoint
Point getMiddlePoint()

Get the region's middle point

Return
Point The region's middle Point
getLastMatch
Match getLastMatch()

Get the Match object of the last find operation

[]
Return
Match Match
getLastMatches
Match[] getLastMatches()

Get the Match objects of the last find operation

Return
Match[] An array of Match
setX
Region setX(x: number)

Set the x coordinate of the top left point

Parameters
x The x coordinate of the top left point
Return
Region This Region instance
setY
Region setY(y: number)

Set the x coordinate of the top left point

Parameters
y The y coordinate of the top left point
Return
Region This Region instance
setW
Region setW(w: number)

Set the width of this region

Parameters
w Width of the region
Return
Region This Region instance
setH
Region setH(h: number)

Set the width of this region

Parameters
h Height of the region
Return
Region This Region instance
noScale
Region noScale()

After calling this, the system will not attempt to scale the region and just use the coordinate as it is

Return
Region This Region instance
left
Region left(percent: number = 0.5)

Shrink the region to the left by percent percent. Negative percent to extend

Paramters
percent percent to shrink/extend
Return
Region A new Region instance
top
Region top(percent: number = 0.5)

Shrink the region to the top by percent percent. Negative percent to extend

Paramters
percent percent to shrink/extend
Return
Region A new Region instance
Region right(percent: number = 0.5)

Shrink the region to the right by percent percent. Negative percent to extend

Paramters
percent percent to shrink/extend
Return
Region A new Region instance
bottom
Region bottom(percent: number = 0.5)

Shrink the region to the bottom by percent percent. Negative percent to extend

Paramters
percent percent to shrink/extend
Return
Region A new Region instance
horizontal
Region horizontal(percent: number = 0.5)

Shrink the region from both left and right by percent percent. Negative percent to extend

Paramters
percent percent to shrink/extend
Return
Region A new Region instance
vertical
Region vertical(percent: number = 0.5)

Shrink the region from both top and bottom by percent percent. Negative percent to extend

Paramters
percent percent to shrink/extend
Return
Region A new Region instance
middle
Region middle(percent: number = 0.5)

Shrink the region from all 4 sides by percent percent. Negative percent to extend

Paramters
percent percent to shrink/extend
Return
Region A new Region instance
pad
Region pad(padLeftPercent: number, padTopPercent: number = 0, padRightPercent: number = 0, padBottomPercent: number = 0)

Pad the region. Shrink it with positive value, enlarge with negative

Parameters
padLeftPercent The left padding in percent
padTopPercent The top padding in percent
padRightPercent The right padding in percent
padBottomPercent The bottom padding in percent
Return
Region A new Region instance
leftPixel
Region leftPixel(pixels: number)

Shrink the region to the left by pixels pixels. Negative pixels to extend

Paramters
pixels pixels to shrink/extend
Return
Region A new Region instance
topPixel
Region topPixel(pixels: number)

Shrink the region to the top by pixels pixels. Negative pixels to extend

Paramters
pixels pixels to shrink/extend
Return
Region A new Region instance
rightPixel
Region rightPixel(pixels: number)

Shrink the region to the right by pixels pixels. Negative pixels to extend

Paramters
pixels pixels to shrink/extend
Return
Region A new Region instance
bottomPixel
Region bottomPixel(pixels: number)

Shrink the region to the bottom by pixels pixels. Negative pixels to extend

Paramters
pixels pixels to shrink/extend
Return
Region A new Region instance
horizontalPixel
Region horizontalPixel(percent: number)

Shrink the region from both left and right by pixels pixels. Negative pixels to extend

Paramters
pixels pixels to shrink/extend
Return
Region A new Region instance
verticalPixel
Region verticalPixel(percent: number)

Shrink the region from both top and bottom by pixels pixels. Negative pixels to extend

Paramters
pixels pixels to shrink/extend
Return
Region A new Region instance
middlePixel
Region middlePixel(percent: number)

Shrink the region from all 4 sides by pixels pixels. Negative pixels to extend

Paramters
pixels pixels to shrink/extend
Return
Region A new Region instance
padPixel
Region padPixel(padLeftPixel: number, padTopPixel: number = 0, padRightPixel: number = 0, padBottomPixel: number = 0)

Pad the region. Shrink it with positive value, enlarge with negative

Parameters
padLeftPixel The left padding in pixel
padTopPixel The top padding in pixel
padRightPixel The right padding in pixel
padBottomPixel The bottom padding in pixel
Return
Region A new Region instance
offset
Region offset(dx: number, dy: number = 0, w: number = null, h: number = null, noScale: bool = false)

Offset the region's coordinate by dx and dy. Optionally change the width and height with w and h. All values are automatically scaled depend on the type of this Region. You can set the 5th parameter to true to disable auto scaling.

Parameters
dx Offset amount in x axis
dy Offset amount in y axis. Default: 0
w New width. Default: null
h New height. Default: null
noScale true to disable auto scaling
Return
Point The new offset Point instance
moveLeft (Deprecated)
Region moveLeft(percent: number)

Move region to the left by percent percent of the device's width.

Deprecated: Please use offset instead

Paramters
percent percent of device's width
Return
Region A new Region instance
moveUp (Deprecated)
Region moveUp(percent: number)

Move region up by percent percent of the device's width.

Deprecated: Please use offset instead

Paramters
percent percent of device's width
Return
Region A new Region instance
moveRight (Deprecated)
Region moveRight(percent: number)

Move region to the right by percent percent of the device's width.

Deprecated: Please use offset instead

Paramters
percent percent of device's width
Return
Region A new Region instance
moveDown (Deprecated)
Region moveDown(percent: number)

Move region down by percent percent of the device's width.

Deprecated: Please use offset instead

Paramters
percent percent of device's width
Return
Region A new Region instance
moveLeftPixel (Deprecated)
Region moveLeftPixel(pixels: number)

Move region to the left by pixels pixels.

Deprecated: Please use offset instead

Paramters
pixels pixels to move
Return
Region A new Region instance
moveUpPixel (Deprecated)
Region moveUpPixel(pixels: number)

Move region up by pixels pixels.

Deprecated: Please use offset instead

Paramters
pixels pixels to move
Return
Region A new Region instance
moveRightPixel (Deprecated)
Region moveRightPixel(pixels: number)

Move region to the right by pixels pixels.

Deprecated: Please use offset instead

Paramters
pixels pixels to move
Return
Region A new Region instance
moveDownPixel (Deprecated)
Region moveDownPixel(pixels: number)

Move region down by pixels pixels.

Deprecated: Please use offset instead

Paramters
pixels pixels to move
Return
Region A new Region instance
find
Match find(image: string | Template, timeout: number | params: FParam)

Find the template image. Return the result with the highest match score

Paramters
imageName Name of the template image
timeout Timeout period in miliseconds
params FParam
Return
Match Match object if found else null
findMulti
Match[] findMulti(imageName: string | Template, timeout: number | params: FParam)

Find the template image. Return all the result(s) with Match Score higher than Min Score

Paramters
imageName Name of the template image
timeout Timeout period in miliseconds
params FParam
Return
Match[] An array of Match object if found else null
findAll
Match[] findAll(imageNames: string[] | Template[], timeout: number | params: FParam)

Find all the template images at the same time. Find operation will only stop when all templates is visible at a given moment or timeout

Paramters
imageNames An array with all template names to find
timeout Timeout period in miliseconds
params FParam
Return
Match[] An array of Match objects with the same length as the input imageNames if all found or null if at least one is not found. All Match object in the array is guaranteed to be non-null
findAny
Match[] findAny(imageNames: string[] | Template[], timeout: number | params: FParam)

Find all the template images at the same time. Find operation will stop as soon as one or more of the template is found

Paramters
imageNames An array with all template names to find
timeout Timeout period in miliseconds
params FParam
Return
Match[] An array of Match objects with the same length as the input imageNames if one or more template is found, null otherwise. Loop through the array to see which template is found. At least one Match object in the array is non-null
click
Match click(imageName: string | Template, timeout: number | params: FParam, repeat: number | clickParams: CParam)

Execute find then click on the result if found

Paramters
imageName Name of the template image
timeout Timeout period in miliseconds
params FParam
repeat Number of time to repeat the click
clickParams CParam
Return
Match Match object if found else null
clickMulti
Match[] clickMulti(imageName: string | Template, timeout: number | params: FParam, repeat: number | clickParams: CParam)

Execute findMulti then click on the result(s) if found

Paramters
imageName Name of the template image
timeout Timeout period in miliseconds
params FParam
repeat Number of time to repeat the click
clickParams CParam
Return
Match[] An array of Match object if found else null
clickAll
Match[] clickAll(imageNames: string[] | Template[], timeout: number | params: FParam, repeat: number | clickParams: CParam)

Execute findAll then click on the result(s) if found

Paramters
imageNames An array with all template names to find
timeout Timeout period in miliseconds
params FParam
repeat Number of time to repeat the click
clickParams CParam
Return
Match[] An array of Match objects with the same length as the input imageNames if all found or null if at least one is not found. All Match object in the array is guaranteed to be non-null
clickAny
Match[] clickAny(imageNames: string[] | Template[], timeout: number | params: FParam, repeat: number | clickParams: CParam)

Execute findAny then click on the result(s) if found

Paramters
imageNames An array with all template names to find
timeout Timeout period in miliseconds
params FParam
repeat Number of time to repeat the click
clickParams CParam
Return
Match[] An array of Match objects with the same length as the input imageNames if one or more template is found, null otherwise. Loop through the array to see which template is found. At least one Match object in the array is non-null
wait
bool wait(imageName: string | Template, timeout: number | params: FParam)

Wait for the template image to disappear

Paramters
imageName Name of the template image
timeout Timeout period in miliseconds
params FParam
Return
bool true if the template disappears within the timeout period, false otherwise.
waitAll
bool waitAll(imageNames: string[] | Template[], timeout: number | params: FParam)

Wait for all template images to disappear

Paramters
imageNames An array with all template names to find
timeout Timeout period in miliseconds
params FParam
Return
Match[] true if all template disappear within the timeout period, false otherwise
findText
Match findText(text: string | Template, timeout: number | params: TParam)

Find the text. Return the result with the highest match score

Paramters
text The text to find
timeout Timeout period in miliseconds
params TParam
Return
Match Match object if found else null
findMultiText
Match[] findMultiText(text: string | Template, timeout: number | params: TParam)

Find the text. Return all the result(s) with Match Score higher than Min Score

Paramters
text The text to find
timeout Timeout period in miliseconds
params TParam
Return
Match[] An array of Match object if found else null
findAllText
Match[] findAllText(texts: string[] | Template[], timeout: number | params: TParam)

Find all the texts at the same time. Find operation will only stop when all texts is visible at a given moment or timeout

Paramters
texts An array with all texts to find
timeout Timeout period in miliseconds
params TParam
Return
Match[] An array of Match objects with the same length as the input texts if all found or null if at least one is not found. All Match object in the array is guaranteed to be non-null
findAnyText
Match[] findAnyText(texts: string[] | Template[], timeout: number | params: TParam)

Find all the texts at the same time. Find operation will stop as soon as one or more of the text is found

Paramters
texts An array with all texts to find
timeout Timeout period in miliseconds
params TParam
Return
Match[] An array of Match objects with the same length as the input texts if one or more text is found, null otherwise. Loop through the array to see which text is found. At least one Match object in the array is non-null
clickText
Match clickText(text: string | Template, timeout: number | params: TParam, repeat: number | clickParams: CParam)

Execute findText then click on the result if found

Paramters
text The text to find
timeout Timeout period in miliseconds
params TParam
repeat Number of time to repeat the click
clickParams CParam
Return
Match Match object if found else null
clickMultiText
Match[] clickMultiText(text: string | Template, timeout: number | params: TParam, repeat: number | clickParams: CParam)

Execute findMultiText then click on the result(s) if found

Paramters
text The text to find
timeout Timeout period in miliseconds
params TParam
repeat Number of time to repeat the click
clickParams CParam
Return
Match[] An array of Match object if found else null
clickAllText
Match[] clickAllText(texts: string[] | Template[], timeout: number | params: TParam, repeat: number | clickParams: CParam)

Execute findAllText then click on the result(s) if found

Paramters
texts An array with all texts to find
timeout Timeout period in miliseconds
params TParam
repeat Number of time to repeat the click
clickParams CParam
Return
Match[] An array of Match objects with the same length as the input texts if all found or null if at least one is not found. All Match object in the array is guaranteed to be non-null
clickAnyText
Match[] clickAnyText(texts: string[] | Template[], timeout: number | params: TParam, repeat: number | clickParams: CParam)

Execute findAnyText then click on the result(s) if found

Paramters
texts An array with all texts to find
timeout Timeout period in miliseconds
params TParam
repeat Number of time to repeat the click
clickParams CParam
Return
Match[] An array of Match objects with the same length as the input texts if one or more text is found, null otherwise. Loop through the array to see which text is found. At least one Match object in the array is non-null
waitText
bool waitText(text: string | Template, timeout: number | params: TParam)

Wait for the text to disappear

Paramters
text The text to find
timeout Timeout period in miliseconds
params TParam
Return
bool true if the text disappears within the timeout period, false otherwise.
waitAllText
bool waitAllText(texts: string[] | Template[], timeout: number | params: TParam)

Wait for all texts to disappear

Paramters
texts An array with all texts to find
timeout Timeout period in miliseconds
params TParam
Return
Match[] true if all texts disappear within the timeout period, false otherwise
highlight
void highlight(color: string = "#e74c3c" | number | Color, width: number, opacity: number = 1)

Highlight this region with the given color

Note: In Android 12, touch can no longer passthrough a window unless the opacity of the window is less than 0.8. If you want to highlight a region and touch through it you must set the opacity to below 0.8
You can use Sys.info("dev.sdk") to check for the Android version of the device

Paramters
color any color code that this method support, number representation or Color object
width Width of the highlight in pixels
opacity Opacity of the region
highlightOff
void highlightOff()

Turn off highlight

capture
bool capture(imageName: string | Template)

Capture the current screen and crop to this region dimensions. The imageName can then be used with any of the image detection method. Image data is saved in-memory, be careful not to use the same name as any other templates as this will override them

Paramters
imageName The name to associate with the image data
Return
bool true if the capture is successful, false otherwise
read
MatchText[] read(param: string | TParam)

Read the text in the region. You can use the returned results to process the information on the screen

Parameters
param string for whitelist parameter or TParam
Return
MatchText[] An array of MatchText
readPlain
string readPlain(param: string | TParam)

Read the text in the region as plain text

Deprecated: Please use readAsString() instead

Parameters
param string for whitelist parameter or TParam
Return
string text in the region. null or defaultValue if fail
readAsString
string readAsString(param: string | TParam, defaultValue: any)

Read the text in the region as plain text

Parameters
param string for whitelist parameter or TParam
defaultValue Value to return when read fail
Return
string text in the region. null or defaultValue if fail to read or there's no text to read. Empty string when text is read but removed by whitelist/blacklist
readAsNumber
number readAsNumber(param: string | TParam, defaultValue: any)

Convenient method that call Num.parse() after readAsString()

Parameters
param string for whitelist parameter or TParam
defaultValue Value to return when read fail
Return
number number in the region. null or defaultValue if fail to read or text is not a number

© 2024 - Macrorify by KoK-CODE