Package org.sikuli.script

Class Region

  • Direct Known Subclasses:
    Match, Screen
    public class Region
extends org.sikuli.script.Element
    A Region is a rectangular area on a screen.

    completely contained in that screen (no screen overlapping)

    NOTES:
    - when needed (find ops), the pixel content is captured from the screen
    - if nothing else is said, the center pixel is the target for mouse actions

    • Nested Class Summary

      • Nested classes/interfaces inherited from class org.sikuli.script.Element

        org.sikuli.script.Element.Interpolation

    • Constructor Summary

      Constructors 
      Constructor Description
      Region​(int X, int Y)
      Convenience: a minimal Region to be used as a Point
      Region​(int X, int Y, int W, int H)
      Create a region with the provided coordinate / size
      Region​(int X, int Y, int W, int H, int screenNumber)
      Create a region with the provided coordinate / size and screen
      Region​(int X, int Y, int W, int H, org.sikuli.script.support.IScreen parentScreen)
      Create a region with the provided coordinate / size and screen
      Region​(java.awt.Dimension size)  
      Region​(java.awt.Rectangle r)
      Create a region from a Rectangle
      Region​(Region r)
      Create a new region from another region.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      Region above()
      create a region above the top side with same width.
      Region above​(int height)
      create a region above the top side with same width and given height
      negative height creates the top part with height inside the region use grow() to include the current region
      Location aboveAt()  
      Location aboveAt​(int offset)
      negative offset goes towards top of screen.
      Region add​(int l, int r, int t, int b)
      resize the region using the given padding values.
      Region add​(Location loc)
      extend the region, so it contains the given point.
      Region add​(Region r)
      extend the region, so it contains the given region.
      void aInput​(java.lang.String text)  
      void aKey​(int key)  
      Location asOffset()
      create a Location object, that can be used as an offset taking the width and hight of this Region
      <PFRML> void aSwipe​(PFRML from, PFRML to)  
      void aSwipeDown()  
      void aSwipeLeft()  
      void aSwipeRight()  
      void aSwipeUp()  
      <PFRML> void aTap​(PFRML target)  
      static Location atMouse()
      Deprecated.
      use Mouse.at() instead
      Region below()
      create a region below the bottom side with same width.
      Region below​(int height)
      create a region below the bottom side with same width and given height.
      Location belowAt()  
      Location belowAt​(int offset)
      positive offset goes towards bottom of screen.
      Region bottom​(java.lang.Number... val)
      At the bottom a new Region with same width is created.
      Region bottomLeft​(java.lang.Number... args)
      In the bottom left corner a new Region is created.
      Region bottomMiddle​(java.lang.Number... args)
      In the bottom middle a new Region is created.
      Region bottomRight​(java.lang.Number... args)
      In the bottom right corner a new Region is created.
      boolean contains​(Location point)
      check if current region contains given point
      boolean contains​(Region region)
      check if current region contains given region
      boolean containsMouse()
      check if mouse pointer is inside current region
      Region copyTo​(int scrID)
      new region with same offset to current screen's top left on given screen
      Region copyTo​(org.sikuli.script.support.IScreen screen)
      new region with same offset to current screen's top left on given screen
      static Region create​(int X, int Y, int W, int H)
      Create a region with the provided top left corner and size
      static Region create​(int X, int Y, int W, int H, org.sikuli.script.support.IScreen scr)
      Create a region with the provided top left corner and size
      static Region create​(java.awt.Rectangle r)
      Create a region from a Rectangle
      static Region create​(Location loc, int w, int h)
      Create a region with the provided top left corner and size
      static Region create​(Location loc, int create_x_direction, int create_y_direction, int w, int h)
      create a region with a corner at the given point.
      static Region create​(Region r)
      Create a region from another region including the region's settings
      void delayType​(int millisecs)
      time in milliseconds to delay between each character at next type only (max 1000)
      int doubleClick()
      double click at the region's last successful match
      use center if no lastMatch
      if region is a match: click targetOffset
      <PFRML> int doubleClick​(PFRML target)
      double click at the given target location.
      <PFRML> int doubleClick​(PFRML target, java.lang.Integer modifiers)
      double click at the given target location.
      <PFRML> int drag​(PFRML target)
      Prepare a drag action: move mouse to given target.
      <PFRML> int dragDrop​(PFRML target)
      Drag from region's last match and drop at given target.
      <PFRML> int dragDrop​(PFRML t1, PFRML t2)
      Drag from a position and drop to another using left mouse button.
      <PFRML> int dropAt​(PFRML target)
      finalize a drag action with a drop: move mouse to given target.
      <PSI> Match exists​(PSI target, double timeout)
      Check if target exists with a specified timeout.
      Match existsText​(java.lang.String text)  
      Match existsText​(java.lang.String text, double timeout)  
      <PSI> Match find​(PSI target)
      finds the given Pattern, String or Image in the region and returns the best match.
      <PSI> org.sikuli.script.Matches findAll​(PSI target)
      finds all occurences of the given Pattern, String or Image in the region and returns an Iterator of Matches.
      <PSI> java.util.List<Match> findAllList​(PSI target)  
      java.util.List<Match> findAllText​(java.lang.String text)  
      java.util.List<Match> findAny​(java.lang.Object... args)  
      java.util.List<Match> findAnyList​(java.util.List<java.lang.Object> pList)  
      Match findText​(java.lang.String text)  
      Location getBottomLeft()  
      Location getBottomRight()  
      Region getCell​(int r, int c)
      get the specified cell counting from (0, 0), if a raster is setup.
      Region getCol​(int c)
      get the specified column counting from 0.
      Region getCol​(int c, int n)
      divide the region in n columns and select column c as new Region
      int getCols()  
      int getColW()  
      org.opencv.core.Mat getContent()  
      static Region getDefaultInstance4py()
      INTERNAL: Get a default Region for Python
      ObserveEvent getEvent​(java.lang.String name)
      the event is removed from the list
      ObserveEvent[] getEvents()
      the region's events are removed from the list
      Image getImage()  
      Region getInset​(Region inset)  
      ScreenImage getLastScreenImage()
      get the last image taken on this regions screen
      java.lang.String getLastScreenImageFile()
      stores the lastScreenImage in the current bundle path with a created unique name
      java.lang.String getLastScreenImageFile​(java.lang.String name)
      stores the lastScreenImage in the current bundle path with the given name
      java.lang.String getLastScreenImageFile​(java.lang.String path, java.lang.String name)
      stores the lastScreenImage in the given path with the given name
      org.sikuli.script.support.Observer getObserver()  
      Region getROI()
      A function only for backward compatibility - Only makes sense with Screen objects
      Region getRow​(int r)
      get the specified row counting from 0.
      Region getRow​(int r, int n)  
      int getRowH()  
      int getRows()  
      org.sikuli.script.support.IScreen getScreenContaining()
      Deprecated.
      Only for compatibility, to get the screen containing this region, use Element.getScreen()
      Region getTile​(int part)  
      Location getTopLeft()  
      Location getTopRight()  
      Region grow()
      create a region enlarged n pixels on each side (n = Settings.DefaultPadding = 50 default)
      Region grow​(int range)
      create a region enlarged range pixels on each side
      Region grow​(int w, int h)
      create a region enlarged w pixels on left and right side and h pixels at top and bottom
      Region grow​(int l, int r, int t, int b)
      create a region enlarged l pixels on left and r pixels right side and t pixels at top side and b pixels a bottom side.
      static Region grow​(Location loc)
      create a minimal region at given point with size 1 x 1
      static Region grow​(Location loc, int w, int h)
      create a region with the given point as center and the given size
      static Region grow​(Location loc, int x, int y, int w, int h)
      create a region with a corner at the given point.
      boolean hasEvents()  
      boolean hasObserver()
      evaluate if at least one event observer is defined for this region (the observer need not be running)
      boolean hasText​(java.lang.String text)  
      Region highlight()
      show a colored frame around the region for a given time or switch on/off
      Region highlight​(double secs)
      show the regions Highlight for the given time in seconds (red frame) if 0 - use the global Settings.SlowMotionDelay
      Region highlight​(double secs, java.lang.String color)
      show the regions Highlight for the given time in seconds (frame of specified color) if 0 - use the global Settings.SlowMotionDelay
      Region highlight​(java.lang.String color)
      Toggle the regions Highlight border (given color).
      Region highlight4py​(java.util.ArrayList args)
      INTERNAL: highlight (for Python support):
      static void highlightAllOff()
      Switch off all actual highlights
      Region highlightOff()
      Switch off the regions highlight
      Region highlightOn()
      Switch on the regions highlight with default color
      Region highlightOn​(java.lang.String color)
      Switch on the regions highlight with given color
      Region inside()
      Deprecated.
      only for backward compatibility
      void internalUseOnlyHighlightReset()
      INTERNAL: ONLY
      boolean isObserving()  
      boolean isRasterValid()
      Can be used to check, wether the Region currently has a valid raster
      boolean isValid()
      Check whether this Region is contained by any of the available screens
      void keyDown​(int keycode)
      press and hold the given key use a constant from java.awt.event.KeyEvent which might be special in the current machine/system environment
      void keyDown​(java.lang.String keys)
      press and hold the given keys including modifier keys.
      void keyUp()
      release all currently pressed keys
      void keyUp​(int keycode)
      release the given keys (see keyDown(keycode) )
      void keyUp​(java.lang.String keys)
      release the given keys (see keyDown(keys) )
      Region left()
      create a region left of the left side with same height.
      Region left​(int width)
      create a region left of the left side with same height and given width.
      Location leftAt()  
      Location leftAt​(int offset)
      negative offset goes to the left.
      Region leftMiddle​(java.lang.Number... args)
      In the left middle a new Region is created.
      Region leftSide​(java.lang.Number... val)
      At the left side a new Region with same height is created.
      static Region make4py​(java.util.ArrayList args)
      Create a new Region
      - Region(x, y, w, h)
      - Region(someRegion)
      Region middle​(java.lang.Number... args)
      Around the center a new Region is created.
      Region morphTo​(Region r)
      Deprecated.
      to be like AWT Rectangle API use setRect() instead
      Region moveTo​(Location loc)
      Deprecated.
      to be like AWT Rectangle API use setLocation()
      Region nearby()
      Deprecated.
      to be like AWT Rectangle API use grow() instead
      Region nearby​(int range)
      Deprecated.
      to be like AWT Rectangle API use grow() instaed
      boolean observe()
      start an observer in this region that runs forever (use stopObserving() in handler) for details about the observe event handler: ObserverCallBack for details about APPEAR/VANISH/CHANGE events: ObserveEvent
      boolean observe​(double secs)
      start an observer in this region for the given time for details about the observe event handler: ObserverCallBack for details about APPEAR/VANISH/CHANGE events: ObserveEvent
      boolean observeInBackground()
      start an observer in this region that runs in background forever - for details about the observe event handler: ObserverCallBack for details about APPEAR/VANISH/CHANGE events: ObserveEvent
      boolean observeInBackground​(double secs)
      start an observer in this region for the given time that runs in background - for details about the observe event handler: ObserverCallBack for details about APPEAR/VANISH/CHANGE events: ObserveEvent
      boolean observeInLine​(double secs)
      INTERNAL: ONLY: for use with scripting API bridges
      Region offset​(int x, int y)
      create region with same size at top left corner offset
      Region offset​(java.lang.Object whatever)
      create region with same size at top left corner offset
      <PSI> java.lang.String onAppear​(PSI target)
      a subsequently started observer in this region should wait for target success and details about the event can be obtained using Observing.
      <PSI> java.lang.String onAppear​(PSI target, java.lang.Object observer)
      a subsequently started observer in this region should wait for target and notify the given observer about this event.
      java.lang.String onChange()
      a subsequently started observer in this region should wait for changes in the region success and details about the event can be obtained using Observing.
      java.lang.String onChange​(java.lang.Integer threshold)
      a subsequently started observer in this region should wait for changes in the region success and details about the event can be obtained using Observing.
      java.lang.String onChange​(java.lang.Integer threshold, java.lang.Object observer)
      a subsequently started observer in this region should wait for changes in the region and notify the given observer about this event for details about the observe event handler: ObserverCallBack for details about APPEAR/VANISH/CHANGE events: ObserveEvent
      java.lang.String onChange​(java.lang.Object observer)
      a subsequently started observer in this region should wait for changes in the region and notify the given observer about this event.
      java.lang.String onChangeDo​(java.lang.Integer threshold, java.lang.Object observer)  
      <PSI> java.lang.String onVanish​(PSI target)
      a subsequently started observer in this region should wait for the target to vanish success and details about the event can be obtained using Observing.
      <PSI> java.lang.String onVanish​(PSI target, java.lang.Object observer)
      a subsequently started observer in this region should wait for the target to vanish and notify the given observer about this event.
      int paste​(java.lang.String text)
      pastes the text at the current position of the focus/carret.
      <PFRML> int paste​(PFRML target, java.lang.String text)
      first does a click(target) at the given target position to gain focus/carret.
      Region right()
      create a region right of the right side with same height.
      Region right​(int width)
      create a region right of the right side with same height and given width.
      Location rightAt()
      point middle on right edge
      Location rightAt​(int offset)
      positive offset goes to the right.
      int rightClick()
      right click at the region's last successful match.
      <PFRML> int rightClick​(PFRML target)
      right click at the given target location
      Pattern or Filename - do a find before and use the match
      Region - position at center
      Match - position at match's targetOffset
      Location - position at that point
      <PFRML> int rightClick​(PFRML target, java.lang.Integer modifiers)
      right click at the given target location
      holding down the given modifier keys
      Pattern or Filename - do a find before and use the match
      Region - position at center
      Match - position at match's targetOffset
      Location - position at that point
      Region rightMiddle​(java.lang.Number... args)
      In the right middle a new Region is created.
      Region rightSide​(java.lang.Number... val)
      At the right side a new Region with same height is created.
      java.lang.String saveCapture​(java.lang.Object... args)  
      void saveLastScreenImage()  
      void setActive​(java.lang.String name)
      set the observer with the given name active (checked while observing)
      Region setBottomLeft​(Location loc)
      Moves the region to the area, whose bottom left corner is the given location
      Region setBottomRight​(Location loc)
      Moves the region to the area, whose bottom right corner is the given location
      Region setCols​(int n)
      store info: this region is divided horizontally into n even columns.
      void setInactive​(java.lang.String name)
      set the observer with the given name inactive (not checked while observing)
      Region setLocation​(Location loc)
      set the regions position.
      Region setRaster​(int r, int c)
      store info: this region is divided into a raster of even cells.
      void setROI()
      resets this region (usually a Screen object) to the coordinates of the containing screen
      void setROI​(int X, int Y, int W, int H)
      resets this region to the given location, and size.
      void setROI​(java.awt.Rectangle r)
      resets this region to the given rectangle.
      void setROI​(Region reg)
      resets this region to the given region.
      Region setRows​(int n)
      store info: this region is divided vertically into n even rows.
      Region setSize​(int W, int H)  
      Region setTopLeft​(Location loc)
      Moves the region to the area, whose top left corner is the given location
      Region setTopRight​(Location loc)
      Moves the region to the area, whose top right corner is the given location
      void stopObserver()
      stops a running observer
      void stopObserver​(java.lang.String message)
      stops a running observer printing an info message
      Region top​(java.lang.Number... val)
      At the top a new Region with same width is created.
      Region topLeft​(java.lang.Number... args)
      In the top left corner a new Region is created.
      Region topMiddle​(java.lang.Number... args)
      In the top middle a new Region is created.
      Region topRight​(java.lang.Number... args)
      In the top right corner a new Region is created.
      java.lang.String toString()
      java.lang.String toStringShort()  
      int type​(java.lang.String text)
      enters the given text one character/key after another using keyDown/keyUp.
      int type​(java.lang.String text, int modifiers)
      enters the given text one character/key after another using keyDown/keyUp.
      int type​(java.lang.String text, java.lang.String modifiers)
      enters the given text one character/key after another using keyDown/keyUp.
      <PFRML> int type​(PFRML target, java.lang.String text)
      first does a click(target) at the given target position to gain focus/carret.
      <PFRML> int type​(PFRML target, java.lang.String text, int modifiers)
      first does a click(target) at the given target position to gain focus/carret
      enters the given text one character/key after another using keyDown/keyUp
      while holding down the given modifier keys
      about the usable Key constants see keyDown(keys)
      Class Key only provides a subset of a US-QWERTY PC keyboard layout
      <PFRML> int type​(PFRML target, java.lang.String text, java.lang.String modifiers)
      first does a click(target) at the given target position to gain focus/carret
      enters the given text one character/key after another using keyDown/keyUp
      while holding down the given modifier keys
      about the usable Key constants see keyDown(keys)
      Class Key only provides a subset of a US-QWERTY PC keyboard layout
      <PSI> Match wait​(PSI target, double timeout)
      Waits for the Pattern, String or Image to appear or timeout (in second) is passed
      Match waitT​(java.lang.String text)  
      Match waitT​(java.lang.String text, double timeout)  
      Match waitText​(java.lang.String text)  
      Match waitText​(java.lang.String text, double timeout)  
      <PSI> boolean waitVanish​(PSI target, double timeout)
      waits until target vanishes or timeout (in seconds) is passed
      int wheel​(int direction, int steps)
      Move the wheel at the current mouse position.
      int wheel​(int direction, int steps, int modifiers)
      Move the wheel at the current mouse position
      the given steps in the given direction:
      Button.WHEEL_DOWN,
      Button.WHEEL_UP
      int wheel​(int direction, int steps, int modifiers, int stepDelay)
      Move the wheel at the current mouse position.
      int wheel​(int direction, int steps, java.lang.String modifiers)
      Move the wheel at the current mouse position.
      int wheel​(int direction, int steps, java.lang.String modifiers, int stepDelay)
      Move the wheel at the current mouse position.
      <PFRML> int wheel​(PFRML target, int direction, int steps)
      move the mouse pointer to the given target location
      and move the wheel the given steps in the given direction:
      Button.WHEEL_DOWN, Button.WHEEL_UP
      <PFRML> int wheel​(PFRML target, int direction, int steps, int modifiers)
      move the mouse pointer to the given target location
      and move the wheel the given steps in the given direction:
      Button.WHEEL_DOWN, Button.WHEEL_UP
      <PFRML> int wheel​(PFRML target, int direction, int steps, int modifiers, int stepDelay)
      move the mouse pointer to the given target location.
      <PFRML> int wheel​(PFRML target, int direction, int steps, java.lang.String modifiers)
      move the mouse pointer to the given target location
      and move the wheel the given steps in the given direction:
      Button.WHEEL_DOWN, Button.WHEEL_UP
      <PFRML> int wheel​(PFRML target, int direction, int steps, java.lang.String modifiers, int stepDelay)
      move the mouse pointer to the given target location.
      int write​(java.lang.String text)
      Compact alternative for type() with more options
      - special keys and options are coded as #XN.

      • Methods inherited from class org.sikuli.script.Element

        asFakeImage, asMaskImage, asText, black, black, cacheStats, click, click, click, cloneContent, collectLines, collectLinesText, collectWords, collectWordsText, createURL, createURL, delayClick, diffPercentage, exists, existsT, file, fileName, findAllByColumn, findAllByRow, findAllT, findBest, findBestList, findChanges, findLine, findLines, findLines, findT, findWord, findWords, findWords, getAll, getAutoWaitTimeout, getBufferedImage, getBufferedImage, getCache, getCenter, getFindFailedHandler, getFindFailedResponse, getH, getImage, getLastMatch, getLastMatches, getMatchLastSeen, getName, getObserveScanRate, getOtherScreen, getPoint, getRect, getRepeatWaitTime, getScreen, getSize, getTarget, getThrowException, getValidImageFilename, getW, getWaitScanRate, getX, getY, has, has, hasT, hasURL, hover, hover, ignoreLastSeen, initScreen, intersection, isFakeImage, isInside, isMaskImage, isOtherScreen, isText, isVirtual, match, match, matches, matches, mean, meanColor, mouseDown, mouseMove, mouseMove, mouseMove, mouseUp, mouseUp, plain, plain, reload, reload, reLocate, resetCache, resetFindFailedResponse, resetThrowException, resize, resize, sameSize, save, save, save, set, set, setAutoWaitTimeout, setCenter, setContent, setFindFailedHandler, setFindFailedResponse, setH, setLocation, setMissingAbort, setMissingPrompt, setName, setObserveScanRate, setOtherScreen, setRect, setRect, setRect, setRepeatWaitTime, setScreen, setThrowException, setVirtual, setW, setWaitScanRate, setX, setX, setY, setY, size, size, stdDev, text, textChar, textLine, textLines, textWord, textWords, traceOff, traceOn, union, unionAll, unionAny, unionAnyList, updateContent, url, url, url, virtual, wait, wait, waitVanish, white

      • Methods inherited from class java.lang.Object

        equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

    • Constructor Detail

      • Region

        public Region​(java.awt.Dimension size)

      • Region

        public Region​(int X,
              int Y,
              int W,
              int H,
              int screenNumber)
        Create a region with the provided coordinate / size and screen
        Parameters:
        X - X position
        Y - Y position
        W - width
        H - heigth
        screenNumber - The number of the screen containing the Region

      • Region

        public Region​(int X,
              int Y,
              int W,
              int H,
              org.sikuli.script.support.IScreen parentScreen)
        Create a region with the provided coordinate / size and screen
        Parameters:
        X - X position
        Y - Y position
        W - width
        H - heigth
        parentScreen - the screen containing the Region

      • Region

        public Region​(int X,
              int Y)
        Convenience: a minimal Region to be used as a Point
        Parameters:
        X - top left x
        Y - top left y

      • Region

        public Region​(int X,
              int Y,
              int W,
              int H)
        Create a region with the provided coordinate / size
        Parameters:
        X - X position
        Y - Y position
        W - width
        H - heigth

      • Region

        public Region​(java.awt.Rectangle r)
        Create a region from a Rectangle
        Parameters:
        r - the Rectangle

      • Region

        public Region​(Region r)
        Create a new region from another region. including the region's settings
        Parameters:
        r - the region

    • Method Detail

      • toString

        public java.lang.String toString()
        Overrides:
        toString in class org.sikuli.script.Element
        Returns:
        the description

      • toStringShort

        public java.lang.String toStringShort()
        Returns:
        a compact description

      • isValid

        public boolean isValid()
        Check whether this Region is contained by any of the available screens
        Overrides:
        isValid in class org.sikuli.script.Element
        Returns:
        true if yes, false otherwise

      • getDefaultInstance4py

        public static Region getDefaultInstance4py()
        INTERNAL: Get a default Region for Python
        Returns:
        the default screen

      • make4py

        public static Region make4py​(java.util.ArrayList args)
        Create a new Region
        - Region(x, y, w, h)
        - Region(someRegion)
        Parameters:
        args -
        Returns:
        new Region

      • create

        public static Region create​(int X,
                            int Y,
                            int W,
                            int H)
        Create a region with the provided top left corner and size
        Parameters:
        X - top left X position
        Y - top left Y position
        W - width
        H - heigth
        Returns:
        then new region

      • create

        public static Region create​(int X,
                            int Y,
                            int W,
                            int H,
                            org.sikuli.script.support.IScreen scr)
        Create a region with the provided top left corner and size
        Parameters:
        X - top left X position
        Y - top left Y position
        W - width
        H - heigth
        scr - the source screen
        Returns:
        the new region

      • create

        public static Region create​(Location loc,
                            int w,
                            int h)
        Create a region with the provided top left corner and size
        Parameters:
        loc - top left corner
        w - width
        h - height
        Returns:
        then new region

      • create

        public static Region create​(Location loc,
                            int create_x_direction,
                            int create_y_direction,
                            int w,
                            int h)
        create a region with a corner at the given point.
        as specified with x y
        0 0 top left
        0 1 bottom left
        1 0 top right
        1 1 bottom right
        Parameters:
        loc - the refence point
        create_x_direction - == 0 is left side !=0 is right side
        create_y_direction - == 0 is top side !=0 is bottom side
        w - the width
        h - the height
        Returns:
        the new region

      • grow

        public static Region grow​(Location loc,
                          int x,
                          int y,
                          int w,
                          int h)
        create a region with a corner at the given point.
        as specified with x y
        0 0 top left
        0 1 bottom left
        1 0 top right
        1 1 bottom right
        same as the corresponding create method, here to be naming compatible with class Location
        Parameters:
        loc - the refence point
        x - ==0 is left side !=0 is right side
        y - ==0 is top side !=0 is bottom side
        w - the width
        h - the height
        Returns:
        the new region

      • create

        public static Region create​(java.awt.Rectangle r)
        Create a region from a Rectangle
        Parameters:
        r - the Rectangle
        Returns:
        the new region

      • create

        public static Region create​(Region r)
        Create a region from another region including the region's settings
        Parameters:
        r - the region
        Returns:
        then new region

      • grow

        public static Region grow​(Location loc,
                          int w,
                          int h)
        create a region with the given point as center and the given size
        Parameters:
        loc - the center point
        w - the width
        h - the height
        Returns:
        the new region

      • grow

        public static Region grow​(Location loc)
        create a minimal region at given point with size 1 x 1
        Parameters:
        loc - the point
        Returns:
        the new region

      • getScreenContaining

        @Deprecated
public org.sikuli.script.support.IScreen getScreenContaining()
        Deprecated.
        Only for compatibility, to get the screen containing this region, use Element.getScreen()
        Returns:
        the screen, that contains the top left corner of the region. Returns primary screen if outside of any screen.

      • setSize

        public Region setSize​(int W,
                      int H)
        Parameters:
        W - new width
        H - new height
        Returns:
        the region itself

      • setROI

        public void setROI()
        resets this region (usually a Screen object) to the coordinates of the containing screen

        Because of the wanted side effect for the containing screen, this should only be used with screen objects. For Region objects use setRect() instead.

      • setROI

        public void setROI​(int X,
                   int Y,
                   int W,
                   int H)
        resets this region to the given location, and size.
        this might move the region even to another screen
        Because of the wanted side effect for the containing screen, this should only be used with screen objects.
        For Region objects use setRect() instead.
        Parameters:
        X - new x
        Y - new y
        W - new width
        H - new height

      • setROI

        public void setROI​(java.awt.Rectangle r)
        resets this region to the given rectangle.
        this might move the region even to another screen
        Because of the wanted side effect for the containing screen, this should only be used with screen objects.
        For Region objects use setRect() instead.
        Parameters:
        r - AWT Rectangle

      • setROI

        public void setROI​(Region reg)
        resets this region to the given region.
        this might move the region even to another screen
        Because of the wanted side effect for the containing screen, this should only be used with screen objects.
        For Region objects use setRect() instead.
        Parameters:
        reg - Region

      • getROI

        public Region getROI()
        A function only for backward compatibility - Only makes sense with Screen objects
        Returns:
        the Region being the current ROI of the containing Screen

      • inside

        @Deprecated
public Region inside()
        Deprecated.
        only for backward compatibility
        Returns:
        the region itself

      • moveTo

        @Deprecated
public Region moveTo​(Location loc)
        Deprecated.
        to be like AWT Rectangle API use setLocation()
        set the regions position.
        this might move the region even to another screen
        Parameters:
        loc - new top left corner
        Returns:
        the region itself

      • setLocation

        public Region setLocation​(Location loc)
        set the regions position.
        this might move the region even to another screen
        Parameters:
        loc - new top left corner
        Returns:
        the region itself

      • morphTo

        @Deprecated
public Region morphTo​(Region r)
        Deprecated.
        to be like AWT Rectangle API use setRect() instead
        set the regions position/size.
        this might move the region even to another screen
        Parameters:
        r - Region
        Returns:
        the region itself

      • add

        public Region add​(int l,
                  int r,
                  int t,
                  int b)
        resize the region using the given padding values.
        might be negative
        Parameters:
        l - padding on left side
        r - padding on right side
        t - padding at top side
        b - padding at bottom side
        Returns:
        the region itself

      • add

        public Region add​(Region r)
        extend the region, so it contains the given region.
        but only the part inside the current screen
        Parameters:
        r - the region to include
        Returns:
        the region itself

      • add

        public Region add​(Location loc)
        extend the region, so it contains the given point.
        but only the part inside the current screen
        Parameters:
        loc - the point to include
        Returns:
        the region itself

      • getImage

        public Image getImage()
        Overrides:
        getImage in class org.sikuli.script.Element

      • getContent

        public org.opencv.core.Mat getContent()
        Overrides:
        getContent in class org.sikuli.script.Element

      • getTile

        public Region getTile​(int part)

      • setRows

        public Region setRows​(int n)
        store info: this region is divided vertically into n even rows.
        a preparation for using getRow()
        Parameters:
        n - number of rows
        Returns:
        the top row

      • setCols

        public Region setCols​(int n)
        store info: this region is divided horizontally into n even columns.
        a preparation for using getCol()
        Parameters:
        n - number of columns
        Returns:
        the leftmost column

      • getRows

        public int getRows()
        Returns:
        the number of rows or null

      • getRowH

        public int getRowH()
        Returns:
        the row height or 0

      • getCols

        public int getCols()
        Returns:
        the number of columns or 0

      • getColW

        public int getColW()
        Returns:
        the columnwidth or 0

      • isRasterValid

        public boolean isRasterValid()
        Can be used to check, wether the Region currently has a valid raster
        Returns:
        true if it has a valid raster (either getCols or getRows or both would return > 0) false otherwise

      • setRaster

        public Region setRaster​(int r,
                        int c)
        store info: this region is divided into a raster of even cells.
        a preparation for using getCell()
        adjusted to a minimum cell size of 5 x 5 pixels
        Parameters:
        r - number of rows
        c - number of columns
        Returns:
        the topleft cell

      • getRow

        public Region getRow​(int r)
        get the specified row counting from 0.
        negative counts reverse from the end (last is -1)
        values outside range are 0 or last respectively
        Parameters:
        r - row number
        Returns:
        the row as new region or the region itself, if no rows are setup

      • getRow

        public Region getRow​(int r,
                     int n)

      • getCol

        public Region getCol​(int c)
        get the specified column counting from 0.
        negative counts reverse from the end (last is -1)
        values outside range are 0 or last respectively
        Parameters:
        c - column number
        Returns:
        the column as new region or the region itself, if no columns are setup

      • getCol

        public Region getCol​(int c,
                     int n)
        divide the region in n columns and select column c as new Region
        Parameters:
        c - the column to select counting from 0 or negative to count from the end
        n - how many columns to devide in
        Returns:
        the selected part or the region itself, if parameters are invalid

      • getCell

        public Region getCell​(int r,
                      int c)
        get the specified cell counting from (0, 0), if a raster is setup.
        negative counts reverse from the end (last = -1) values outside range are 0 or last respectively
        Parameters:
        r - row number
        c - column number
        Returns:
        the cell as new region or the region itself, if no raster is setup

      • topLeft

        public Region topLeft​(java.lang.Number... args)
        In the top left corner a new Region is created.
        • no parameter: width/2 and height/2
        • one number: new width and height/2
        • two numbers: new width and new height

        if the number is 0, the respective value is value/2

        if the number is a decimal between 0 and one, the respective value is value*number

        if the number is greater 1, it is the new value

        it is an error, if the value is greater than the actual width or height respectively

        Parameters:
        args - 0 .. 2 numbers (more than 2 values is an error)
        Returns:
        a new Region or the given Region in case of error

      • topRight

        public Region topRight​(java.lang.Number... args)
        In the top right corner a new Region is created.

        about the parameters see: topLeft(java.lang.Number...)

        Parameters:
        args - 0 .. 2 numbers (more than 2 values is an error)
        Returns:
        a new Region or the given Region in case of error

      • top

        public Region top​(java.lang.Number... val)
        At the top a new Region with same width is created.

        about the parameter see: topLeft(java.lang.Number...)

        Parameters:
        val - number for the new height (omitted means 0)
        Returns:
        a new Region or the given Region in case of error

      • topMiddle

        public Region topMiddle​(java.lang.Number... args)
        In the top middle a new Region is created.

        about the parameters see: topLeft(java.lang.Number...)

        Parameters:
        args - 0 .. 2 numbers (more than 2 values is an error)
        Returns:
        a new Region or the given Region in case of error

      • leftMiddle

        public Region leftMiddle​(java.lang.Number... args)
        In the left middle a new Region is created.

        about the parameters see: topLeft(java.lang.Number...)

        Parameters:
        args - 0 .. 2 numbers (more than 2 values is an error)
        Returns:
        a new Region or the given Region in case of error

      • leftSide

        public Region leftSide​(java.lang.Number... val)
        At the left side a new Region with same height is created.

        about the parameter see: topLeft(java.lang.Number...)

        Parameters:
        val - number for the new width (omitted means 0)
        Returns:
        a new Region or the given Region in case of error

      • rightMiddle

        public Region rightMiddle​(java.lang.Number... args)
        In the right middle a new Region is created.

        about the parameters see: topLeft(java.lang.Number...)

        Parameters:
        args - 0 .. 2 numbers (more than 2 values is an error)
        Returns:
        a new Region or the given Region in case of error

      • rightSide

        public Region rightSide​(java.lang.Number... val)
        At the right side a new Region with same height is created.

        about the parameter see: topLeft(java.lang.Number...)

        Parameters:
        val - number for the new width (omitted means 0)
        Returns:
        a new Region or the given Region in case of error

      • bottomLeft

        public Region bottomLeft​(java.lang.Number... args)
        In the bottom left corner a new Region is created.

        about the parameters see: topLeft(java.lang.Number...)

        Parameters:
        args - 0 .. 2 numbers (more than 2 values is an error)
        Returns:
        a new Region or the given Region in case of error

      • bottomRight

        public Region bottomRight​(java.lang.Number... args)
        In the bottom right corner a new Region is created.

        about the parameters see: topLeft(java.lang.Number...)

        Parameters:
        args - 0 .. 2 numbers (more than 2 values is an error)
        Returns:
        a new Region or the given Region in case of error

      • bottom

        public Region bottom​(java.lang.Number... val)
        At the bottom a new Region with same width is created.

        about the parameter see: topLeft(java.lang.Number...)

        Parameters:
        val - number for the new height (omitted means 0)
        Returns:
        a new Region or the given Region in case of error

      • bottomMiddle

        public Region bottomMiddle​(java.lang.Number... args)
        In the bottom middle a new Region is created.

        about the parameters see: topLeft(java.lang.Number...)

        Parameters:
        args - 0 .. 2 numbers (more than 2 values is an error)
        Returns:
        a new Region or the given Region in case of error

      • middle

        public Region middle​(java.lang.Number... args)
        Around the center a new Region is created.

        about the parameters see: topLeft(java.lang.Number...)

        Parameters:
        args - 0 .. 2 numbers (more than 2 values is an error)
        Returns:
        a new Region or the given Region in case of error

      • contains

        public boolean contains​(Region region)
        check if current region contains given region
        Parameters:
        region - the other Region
        Returns:
        true/false

      • offset

        public Region offset​(java.lang.Object whatever)
        create region with same size at top left corner offset
        Parameters:
        whatever - offset taken from Region, Match, Image, Location or Offset
        Returns:
        the new region

      • offset

        public Region offset​(int x,
                     int y)
        create region with same size at top left corner offset
        Parameters:
        x - horizontal offset
        y - vertical offset
        Returns:
        the new region

      • nearby

        @Deprecated
public Region nearby()
        Deprecated.
        to be like AWT Rectangle API use grow() instead
        create a region enlarged Settings.DefaultPadding pixels on each side
        Returns:
        the new region

      • nearby

        @Deprecated
public Region nearby​(int range)
        Deprecated.
        to be like AWT Rectangle API use grow() instaed
        create a region enlarged range pixels on each side
        Parameters:
        range - the margin to be added around
        Returns:
        the new region

      • grow

        public Region grow()
        create a region enlarged n pixels on each side (n = Settings.DefaultPadding = 50 default)
        Returns:
        the new region

      • grow

        public Region grow​(int range)
        create a region enlarged range pixels on each side
        Parameters:
        range - the margin to be added around
        Returns:
        the new region

      • grow

        public Region grow​(int w,
                   int h)
        create a region enlarged w pixels on left and right side and h pixels at top and bottom
        Parameters:
        w - pixels horizontally
        h - pixels vertically
        Returns:
        the new region

      • grow

        public Region grow​(int l,
                   int r,
                   int t,
                   int b)
        create a region enlarged l pixels on left and r pixels right side and t pixels at top side and b pixels a bottom side. negative values go inside (shrink)
        Parameters:
        l - add to the left
        r - add to right
        t - add above
        b - add beneath
        Returns:
        the new region

      • right

        public Region right()
        create a region right of the right side with same height. the new region extends to the right screen border.
        use grow() to include the current region
        Returns:
        the new region

      • right

        public Region right​(int width)
        create a region right of the right side with same height and given width.
        negative width creates the right part with width inside the region
        use grow() to include the current region
        Parameters:
        width - pixels
        Returns:
        the new region

      • left

        public Region left()
        create a region left of the left side with same height.
        the new region extends to the left screen border
        use grow() to include the current region
        Returns:
        the new region

      • left

        public Region left​(int width)
        create a region left of the left side with same height and given width.
        negative width creates the left part with width inside the region use grow() to include the current region
        Parameters:
        width - pixels
        Returns:
        the new region

      • above

        public Region above()
        create a region above the top side with same width.
        the new region extends to the top screen border
        use grow() to include the current region
        Returns:
        the new region

      • above

        public Region above​(int height)
        create a region above the top side with same width and given height
        negative height creates the top part with height inside the region use grow() to include the current region
        Parameters:
        height - pixels
        Returns:
        the new region

      • below

        public Region below()
        create a region below the bottom side with same width.
        the new region extends to the bottom screen border
        use grow() to include the current region
        Returns:
        the new region

      • below

        public Region below​(int height)
        create a region below the bottom side with same width and given height.
        negative height creates the bottom part with height inside the region use grow() to include the current region
        Parameters:
        height - pixels
        Returns:
        the new region

      • getTopLeft

        public Location getTopLeft()
        Returns:
        top left corner Location

      • setTopLeft

        public Region setTopLeft​(Location loc)
        Moves the region to the area, whose top left corner is the given location
        Parameters:
        loc - the location which is the new top left point of the region
        Returns:
        the region itself

      • getTopRight

        public Location getTopRight()
        Returns:
        top right corner Location

      • setTopRight

        public Region setTopRight​(Location loc)
        Moves the region to the area, whose top right corner is the given location
        Parameters:
        loc - the location which is the new top right point of the region
        Returns:
        the region itself

      • getBottomLeft

        public Location getBottomLeft()
        Returns:
        bottom left corner Location

      • setBottomLeft

        public Region setBottomLeft​(Location loc)
        Moves the region to the area, whose bottom left corner is the given location
        Parameters:
        loc - the location which is the new bottom left point of the region
        Returns:
        the region itself

      • getBottomRight

        public Location getBottomRight()
        Returns:
        bottom right corner Location

      • setBottomRight

        public Region setBottomRight​(Location loc)
        Moves the region to the area, whose bottom right corner is the given location
        Parameters:
        loc - the location which is the new bottom right point of the region
        Returns:
        the region itself

      • atMouse

        @Deprecated
public static Location atMouse()
        Deprecated.
        use Mouse.at() instead
        Returns:
        current location of mouse pointer

      • contains

        public boolean contains​(Location point)
        check if current region contains given point
        Parameters:
        point - Point
        Returns:
        true/false

      • containsMouse

        public boolean containsMouse()
        check if mouse pointer is inside current region
        Returns:
        true/false

      • copyTo

        public Region copyTo​(int scrID)
        new region with same offset to current screen's top left on given screen
        Parameters:
        scrID - number of screen
        Returns:
        new region

      • copyTo

        public Region copyTo​(org.sikuli.script.support.IScreen screen)
        new region with same offset to current screen's top left on given screen
        Parameters:
        screen - new parent screen
        Returns:
        new region

      • asOffset

        public Location asOffset()
        create a Location object, that can be used as an offset taking the width and hight of this Region
        Returns:
        a new Location object with width and height as x and y

      • rightAt

        public Location rightAt()
        point middle on right edge
        Returns:
        point middle on right edge

      • rightAt

        public Location rightAt​(int offset)
        positive offset goes to the right. might be off current screen
        Parameters:
        offset - pixels
        Returns:
        point with given offset horizontally to middle point on right edge

      • leftAt

        public Location leftAt()
        Returns:
        point middle on left edge

      • leftAt

        public Location leftAt​(int offset)
        negative offset goes to the left.
        might be off current screen
        Parameters:
        offset - pixels
        Returns:
        point with given offset horizontally to middle point on left edge

      • aboveAt

        public Location aboveAt()
        Returns:
        point middle on top edge

      • aboveAt

        public Location aboveAt​(int offset)
        negative offset goes towards top of screen.
        might be off current screen
        Parameters:
        offset - pixels
        Returns:
        point with given offset vertically to middle point on top edge

      • belowAt

        public Location belowAt()
        Returns:
        point middle on bottom edge

      • belowAt

        public Location belowAt​(int offset)
        positive offset goes towards bottom of screen.
        might be off current screen
        Parameters:
        offset - pixels
        Returns:
        point with given offset vertically to middle point on bottom edge

      • wait

        public <PSI> Match wait​(PSI target,
                        double timeout)
                 throws FindFailed
        Waits for the Pattern, String or Image to appear or timeout (in second) is passed
        Overrides:
        wait in class org.sikuli.script.Element
        Type Parameters:
        PSI - Pattern, String or Image
        Parameters:
        target - The target to search for
        timeout - Timeout in seconds
        Returns:
        The found Match
        Throws:
        FindFailed - if the Find operation finally failed

      • find

        public <PSI> Match find​(PSI target)
                 throws FindFailed
        finds the given Pattern, String or Image in the region and returns the best match.
        Overrides:
        find in class org.sikuli.script.Element
        Type Parameters:
        PSI - Pattern, String or Image
        Parameters:
        target - what (PSI) to find
        Returns:
        If found, the element. null otherwise
        Throws:
        FindFailed - if the Find operation failed

      • exists

        public <PSI> Match exists​(PSI target,
                          double timeout)
        Check if target exists with a specified timeout.
        timout = 0: returns immediately after first search, does not raise FindFailed
        Overrides:
        exists in class org.sikuli.script.Element
        Type Parameters:
        PSI - Pattern, String or Image
        Parameters:
        target - The target to search for
        timeout - Timeout in seconds
        Returns:
        the match (null if not found or image file missing)

      • waitVanish

        public <PSI> boolean waitVanish​(PSI target,
                                double timeout)
        waits until target vanishes or timeout (in seconds) is passed
        Overrides:
        waitVanish in class org.sikuli.script.Element
        Type Parameters:
        PSI - Pattern, String or Image
        Parameters:
        target - Pattern, String or Image
        timeout - time in seconds
        Returns:
        true if target vanishes, false otherwise and if imagefile is missing.

      • findAll

        public <PSI> org.sikuli.script.Matches findAll​(PSI target)
                                        throws FindFailed
        finds all occurences of the given Pattern, String or Image in the region and returns an Iterator of Matches.
        Overrides:
        findAll in class org.sikuli.script.Element
        Type Parameters:
        PSI - Pattern, String or Image
        Parameters:
        target - A search criteria
        Returns:
        All elements matching
        Throws:
        FindFailed - if the Find operation failed

      • findAllList

        public <PSI> java.util.List<Match> findAllList​(PSI target)

      • findAny

        public java.util.List<Match> findAny​(java.lang.Object... args)
        Overrides:
        findAny in class org.sikuli.script.Element

      • findAnyList

        public java.util.List<Match> findAnyList​(java.util.List<java.lang.Object> pList)
        Overrides:
        findAnyList in class org.sikuli.script.Element

      • findText

        public Match findText​(java.lang.String text)
               throws FindFailed
        Overrides:
        findText in class org.sikuli.script.Element
        Throws:
        FindFailed

      • existsText

        public Match existsText​(java.lang.String text,
                        double timeout)

      • existsText

        public Match existsText​(java.lang.String text)
        Overrides:
        existsText in class org.sikuli.script.Element

      • hasText

        public boolean hasText​(java.lang.String text)
        Overrides:
        hasText in class org.sikuli.script.Element

      • findAllText

        public java.util.List<Match> findAllText​(java.lang.String text)
        Overrides:
        findAllText in class org.sikuli.script.Element

      • highlight4py

        public Region highlight4py​(java.util.ArrayList args)
        INTERNAL: highlight (for Python support): 
         all act on the related Region
 () - on/off,
 (int) - int seconds
 (String) - on/off with given color
 (int,String) - int seconds with given color
 (float), (float,String) - same as int
        Parameters:
        args - values as above
        Returns:
        this

      • internalUseOnlyHighlightReset

        public void internalUseOnlyHighlightReset()
        INTERNAL: ONLY

      • highlightAllOff

        public static void highlightAllOff()
        Switch off all actual highlights

      • highlightOn

        public Region highlightOn()
        Switch on the regions highlight with default color
        Returns:
        this Region

      • highlightOn

        public Region highlightOn​(java.lang.String color)
        Switch on the regions highlight with given color
        Parameters:
        color - Color of frame (see method highlight(color))
        Returns:
        this Region

      • highlightOff

        public Region highlightOff()
        Switch off the regions highlight
        Returns:
        this Region

      • highlight

        public Region highlight()
        show a colored frame around the region for a given time or switch on/off

        () or (color) switch on/off with color (default red)

        (number) or (number, color) show in color (default red) for number seconds (cut to int)

        Returns:
        this region

      • highlight

        public Region highlight​(java.lang.String color)
        Toggle the regions Highlight border (given color).
        allowed color specifications for frame color:
        - a color name out of: black, blue, cyan, gray, green, magenta, orange, pink, red, white, yellow (lowercase and uppercase can be mixed, internally transformed to all uppercase)
        - these colornames exactly written: lightGray, LIGHT_GRAY, darkGray and DARK_GRAY
        - a hex value like in HTML: #XXXXXX (max 6 hex digits)
        - an RGB specification as: #rrrgggbbb where rrr, ggg, bbb are integer values in range 0 - 255 padded with leading zeros if needed (hence exactly 9 digits)
        Parameters:
        color - Color of frame
        Returns:
        the region itself

      • highlight

        public Region highlight​(double secs)
        show the regions Highlight for the given time in seconds (red frame) if 0 - use the global Settings.SlowMotionDelay
        Parameters:
        secs - time in seconds
        Returns:
        the region itself

      • highlight

        public Region highlight​(double secs,
                        java.lang.String color)
        show the regions Highlight for the given time in seconds (frame of specified color) if 0 - use the global Settings.SlowMotionDelay
        Parameters:
        secs - time in seconds
        color - Color of frame (see method highlight(color))
        Returns:
        the region itself

      • getObserver

        public org.sikuli.script.support.Observer getObserver()

      • hasObserver

        public boolean hasObserver()
        evaluate if at least one event observer is defined for this region (the observer need not be running)
        Returns:
        true, if the region has an observer with event observers

      • isObserving

        public boolean isObserving()
        Returns:
        true if an observer is running for this region

      • hasEvents

        public boolean hasEvents()
        Returns:
        true if any events have happened for this region, false otherwise

      • getEvents

        public ObserveEvent[] getEvents()
        the region's events are removed from the list
        Returns:
        the region's happened events as array if any (size might be 0)

      • getEvent

        public ObserveEvent getEvent​(java.lang.String name)
        the event is removed from the list
        Parameters:
        name - event's name
        Returns:
        the named event if happened otherwise null

      • setInactive

        public void setInactive​(java.lang.String name)
        set the observer with the given name inactive (not checked while observing)
        Parameters:
        name - observers name

      • setActive

        public void setActive​(java.lang.String name)
        set the observer with the given name active (checked while observing)
        Parameters:
        name - observers name

      • onAppear

        public <PSI> java.lang.String onAppear​(PSI target,
                                       java.lang.Object observer)
        a subsequently started observer in this region should wait for target and notify the given observer about this event.
        for details about the observe event handler: ObserverCallBack
        for details about APPEAR/VANISH/CHANGE events: ObserveEvent
        Type Parameters:
        PSI - Pattern, String or Image
        Parameters:
        target - Pattern, String or Image
        observer - ObserverCallBack
        Returns:
        the event's name

      • onAppear

        public <PSI> java.lang.String onAppear​(PSI target)
        a subsequently started observer in this region should wait for target success and details about the event can be obtained using Observing.
        for details about APPEAR/VANISH/CHANGE events: ObserveEvent
        Type Parameters:
        PSI - Pattern, String or Image
        Parameters:
        target - Pattern, String or Image
        Returns:
        the event's name

      • onVanish

        public <PSI> java.lang.String onVanish​(PSI target,
                                       java.lang.Object observer)
        a subsequently started observer in this region should wait for the target to vanish and notify the given observer about this event.
        for details about the observe event handler: ObserverCallBack
        for details about APPEAR/VANISH/CHANGE events: ObserveEvent
        Type Parameters:
        PSI - Pattern, String or Image
        Parameters:
        target - Pattern, String or Image
        observer - ObserverCallBack
        Returns:
        the event's name

      • onVanish

        public <PSI> java.lang.String onVanish​(PSI target)
        a subsequently started observer in this region should wait for the target to vanish success and details about the event can be obtained using Observing.
        for details about APPEAR/VANISH/CHANGE events: ObserveEvent
        Type Parameters:
        PSI - Pattern, String or Image
        Parameters:
        target - Pattern, String or Image
        Returns:
        the event's name

      • onChange

        public java.lang.String onChange​(java.lang.Integer threshold,
                                 java.lang.Object observer)
        a subsequently started observer in this region should wait for changes in the region and notify the given observer about this event for details about the observe event handler: ObserverCallBack for details about APPEAR/VANISH/CHANGE events: ObserveEvent
        Parameters:
        threshold - minimum size of changes (rectangle threshhold x threshold)
        observer - ObserverCallBack
        Returns:
        the event's name

      • onChange

        public java.lang.String onChange​(java.lang.Integer threshold)
        a subsequently started observer in this region should wait for changes in the region success and details about the event can be obtained using Observing.
        for details about APPEAR/VANISH/CHANGE events: ObserveEvent
        Parameters:
        threshold - minimum size of changes (rectangle threshhold x threshold)
        Returns:
        the event's name

      • onChange

        public java.lang.String onChange​(java.lang.Object observer)
        a subsequently started observer in this region should wait for changes in the region and notify the given observer about this event.
        minimum size of changes used: Settings.ObserveMinChangedPixels for details about the observe event handler: ObserverCallBack for details about APPEAR/VANISH/CHANGE events: ObserveEvent
        Parameters:
        observer - ObserverCallBack
        Returns:
        the event's name

      • onChange

        public java.lang.String onChange()
        a subsequently started observer in this region should wait for changes in the region success and details about the event can be obtained using Observing.
        minimum size of changes used: Settings.ObserveMinChangedPixels for details about APPEAR/VANISH/CHANGE events: ObserveEvent
        Returns:
        the event's name

      • onChangeDo

        public java.lang.String onChangeDo​(java.lang.Integer threshold,
                                   java.lang.Object observer)

      • observe

        public boolean observe()
        start an observer in this region that runs forever (use stopObserving() in handler) for details about the observe event handler: ObserverCallBack for details about APPEAR/VANISH/CHANGE events: ObserveEvent
        Returns:
        false if not possible, true if events have happened

      • observe

        public boolean observe​(double secs)
        start an observer in this region for the given time for details about the observe event handler: ObserverCallBack for details about APPEAR/VANISH/CHANGE events: ObserveEvent
        Parameters:
        secs - time in seconds the observer should run
        Returns:
        false if not possible, true if events have happened

      • observeInLine

        public boolean observeInLine​(double secs)
        INTERNAL: ONLY: for use with scripting API bridges
        Parameters:
        secs - time in seconds the observer should run
        Returns:
        false if not possible, true if events have happened

      • observeInBackground

        public boolean observeInBackground​(double secs)
        start an observer in this region for the given time that runs in background - for details about the observe event handler: ObserverCallBack for details about APPEAR/VANISH/CHANGE events: ObserveEvent
        Parameters:
        secs - time in seconds the observer should run
        Returns:
        false if not possible, true otherwise

      • observeInBackground

        public boolean observeInBackground()
        start an observer in this region that runs in background forever - for details about the observe event handler: ObserverCallBack for details about APPEAR/VANISH/CHANGE events: ObserveEvent
        Returns:
        false if not possible, true otherwise

      • stopObserver

        public void stopObserver()
        stops a running observer

      • stopObserver

        public void stopObserver​(java.lang.String message)
        stops a running observer printing an info message
        Parameters:
        message - text

      • doubleClick

        public int doubleClick()
        double click at the region's last successful match
        use center if no lastMatch
        if region is a match: click targetOffset
        Returns:
        1 if possible, 0 otherwise

      • doubleClick

        public <PFRML> int doubleClick​(PFRML target)
                        throws FindFailed
        double click at the given target location.
        Pattern or Filename - do a find before and use the match
        Region - position at center
        Match - position at match's targetOffset
        Location - position at that point
        Type Parameters:
        PFRML - Pattern, Filename, Text, Region, Match or Location
        Parameters:
        target - Pattern, Filename, Text, Region, Match or Location
        Returns:
        1 if possible, 0 otherwise
        Throws:
        FindFailed - for Pattern or Filename

      • doubleClick

        public <PFRML> int doubleClick​(PFRML target,
                               java.lang.Integer modifiers)
                        throws FindFailed
        double click at the given target location.
        holding down the given modifier keys
        Pattern or Filename - do a find before and use the match
        Region - position at center
        Match - position at match's targetOffset
        Location - position at that point
        Type Parameters:
        PFRML - Pattern, Filename, Text, Region, Match or Location
        Parameters:
        target - Pattern, Filename, Text, Region, Match or Location
        modifiers - the value of the resulting bitmask (see KeyModifier)
        Returns:
        1 if possible, 0 otherwise
        Throws:
        FindFailed - for Pattern or Filename

      • rightClick

        public int rightClick()
        right click at the region's last successful match.
        use center if no lastMatch
        if region is a match: click targetOffset
        Returns:
        1 if possible, 0 otherwise

      • rightClick

        public <PFRML> int rightClick​(PFRML target)
                       throws FindFailed
        right click at the given target location
        Pattern or Filename - do a find before and use the match
        Region - position at center
        Match - position at match's targetOffset
        Location - position at that point
        Type Parameters:
        PFRML - Pattern, Filename, Text, Region, Match or Location
        Parameters:
        target - Pattern, Filename, Text, Region, Match or Location
        Returns:
        1 if possible, 0 otherwise
        Throws:
        FindFailed - for Pattern or Filename

      • rightClick

        public <PFRML> int rightClick​(PFRML target,
                              java.lang.Integer modifiers)
                       throws FindFailed
        right click at the given target location
        holding down the given modifier keys
        Pattern or Filename - do a find before and use the match
        Region - position at center
        Match - position at match's targetOffset
        Location - position at that point
        Type Parameters:
        PFRML - Pattern, Filename, Text, Region, Match or Location
        Parameters:
        target - Pattern, Filename, Text, Region, Match or Location
        modifiers - the value of the resulting bitmask (see KeyModifier)
        Returns:
        1 if possible, 0 otherwise
        Throws:
        FindFailed - for Pattern or Filename

      • dragDrop

        public <PFRML> int dragDrop​(PFRML target)
                     throws FindFailed
        Drag from region's last match and drop at given target.
        applying Settings.DelayAfterDrag and DelayBeforeDrop
        using left mouse button
        Type Parameters:
        PFRML - Pattern, Filename, Text, Region, Match or Location
        Parameters:
        target - Pattern, Filename, Text, Region, Match or Location
        Returns:
        1 if possible, 0 otherwise
        Throws:
        FindFailed - if the Find operation failed

      • dragDrop

        public <PFRML> int dragDrop​(PFRML t1,
                            PFRML t2)
                     throws FindFailed
        Drag from a position and drop to another using left mouse button.
        applying Settings.DelayAfterDrag and DelayBeforeDrop
        Type Parameters:
        PFRML - Pattern, Filename, Text, Region, Match or Location
        Parameters:
        t1 - source position
        t2 - destination position
        Returns:
        1 if possible, 0 otherwise
        Throws:
        FindFailed - if the Find operation failed

      • drag

        public <PFRML> int drag​(PFRML target)
                 throws FindFailed
        Prepare a drag action: move mouse to given target.
        press and hold left mouse button
        wait Settings.DelayAfterDrag
        Type Parameters:
        PFRML - Pattern, Filename, Text, Region, Match or Location
        Parameters:
        target - Pattern, Filename, Text, Region, Match or Location
        Returns:
        1 if possible, 0 otherwise
        Throws:
        FindFailed - if not found

      • dropAt

        public <PFRML> int dropAt​(PFRML target)
                   throws FindFailed
        finalize a drag action with a drop: move mouse to given target.
        wait Settings.DelayBeforeDrop before releasing the left mouse button
        Type Parameters:
        PFRML - Pattern, Filename, Text, Region, Match or Location
        Parameters:
        target - Pattern, Filename, Text, Region, Match or Location
        Returns:
        1 if possible, 0 otherwise
        Throws:
        FindFailed - if not found

      • wheel

        public int wheel​(int direction,
                 int steps)
        Move the wheel at the current mouse position.
        the given steps in the given direction:
        Button.WHEEL_DOWN,
        Button.WHEEL_UP
        Parameters:
        direction - to move the wheel
        steps - the number of steps
        Returns:
        1 in any case

      • wheel

        public int wheel​(int direction,
                 int steps,
                 java.lang.String modifiers)
        Move the wheel at the current mouse position.
        the given steps in the given direction:
        Button.WHEEL_DOWN,
        Button.WHEEL_UP
        Parameters:
        direction - to move the wheel
        steps - the number of steps
        modifiers - constants according to class Key - combine using +
        Returns:
        1 in any case

      • wheel

        public int wheel​(int direction,
                 int steps,
                 int modifiers)
        Move the wheel at the current mouse position
        the given steps in the given direction:
        Button.WHEEL_DOWN,
        Button.WHEEL_UP
        Parameters:
        direction - to move the wheel
        steps - the number of steps
        modifiers - the value of the resulting bitmask (see KeyModifier)
        Returns:
        1 in any case

      • wheel

        public int wheel​(int direction,
                 int steps,
                 java.lang.String modifiers,
                 int stepDelay)
        Move the wheel at the current mouse position.
        the given steps in the given direction:
        Button.WHEEL_DOWN,
        Button.WHEEL_UP
        Parameters:
        direction - to move the wheel
        steps - the number of steps
        modifiers - constants according to class Key - combine using +
        stepDelay - number of milliseconds to wait when incrementing the step value
        Returns:
        1 in any case

      • wheel

        public int wheel​(int direction,
                 int steps,
                 int modifiers,
                 int stepDelay)
        Move the wheel at the current mouse position.
        the given steps in the given direction:
        Button.WHEEL_DOWN,
        Button.WHEEL_UP
        Parameters:
        direction - to move the wheel
        steps - the number of steps
        modifiers - the value of the resulting bitmask (see KeyModifier)
        stepDelay - number of milliseconds to wait when incrementing the step value
        Returns:
        1 in any case

      • wheel

        public <PFRML> int wheel​(PFRML target,
                         int direction,
                         int steps)
                  throws FindFailed
        move the mouse pointer to the given target location
        and move the wheel the given steps in the given direction:
        Button.WHEEL_DOWN, Button.WHEEL_UP
        Type Parameters:
        PFRML - Pattern, Filename, Text, Region, Match or Location target
        Parameters:
        target - Pattern, Filename, Text, Region, Match or Location
        direction - to move the wheel
        steps - the number of steps
        Returns:
        1 if possible, 0 otherwise
        Throws:
        FindFailed - if the Find operation failed

      • wheel

        public <PFRML> int wheel​(PFRML target,
                         int direction,
                         int steps,
                         java.lang.String modifiers)
                  throws FindFailed
        move the mouse pointer to the given target location
        and move the wheel the given steps in the given direction:
        Button.WHEEL_DOWN, Button.WHEEL_UP
        Type Parameters:
        PFRML - Pattern, Filename, Text, Region, Match or Location target
        Parameters:
        target - Pattern, Filename, Text, Region, Match or Location
        direction - to move the wheel
        steps - the number of steps
        modifiers - constants according to class Key - combine using +
        Returns:
        1 if possible, 0 otherwise
        Throws:
        FindFailed - if the Find operation failed

      • wheel

        public <PFRML> int wheel​(PFRML target,
                         int direction,
                         int steps,
                         int modifiers)
                  throws FindFailed
        move the mouse pointer to the given target location
        and move the wheel the given steps in the given direction:
        Button.WHEEL_DOWN, Button.WHEEL_UP
        Type Parameters:
        PFRML - Pattern, Filename, Text, Region, Match or Location target
        Parameters:
        target - Pattern, Filename, Text, Region, Match or Location
        direction - to move the wheel
        steps - the number of steps
        modifiers - the value of the resulting bitmask (see KeyModifier)
        Returns:
        1 if possible, 0 otherwise
        Throws:
        FindFailed - if the Find operation failed

      • wheel

        public <PFRML> int wheel​(PFRML target,
                         int direction,
                         int steps,
                         java.lang.String modifiers,
                         int stepDelay)
                  throws FindFailed
        move the mouse pointer to the given target location.
        and move the wheel the given steps in the given direction:
        Button.WHEEL_DOWN, Button.WHEEL_UP
        Type Parameters:
        PFRML - Pattern, Filename, Text, Region, Match or Location target
        Parameters:
        target - Pattern, Filename, Text, Region, Match or Location
        direction - to move the wheel
        steps - the number of steps
        modifiers - constants according to class Key - combine using +
        stepDelay - number of milliseconds to wait when incrementing the step value
        Returns:
        1 if possible, 0 otherwise
        Throws:
        FindFailed - if the Find operation failed

      • wheel

        public <PFRML> int wheel​(PFRML target,
                         int direction,
                         int steps,
                         int modifiers,
                         int stepDelay)
                  throws FindFailed
        move the mouse pointer to the given target location.
        and move the wheel the given steps in the given direction:
        Button.WHEEL_DOWN, Button.WHEEL_UP
        Type Parameters:
        PFRML - Pattern, Filename, Text, Region, Match or Location target
        Parameters:
        target - Pattern, Filename, Text, Region, Match or Location
        direction - to move the wheel
        steps - the number of steps
        modifiers - constants according to class Key - combine using +
        stepDelay - number of milliseconds to wait when incrementing the step value
        Returns:
        1 if possible, 0 otherwise
        Throws:
        FindFailed - if the Find operation failed

      • write

        public int write​(java.lang.String text)
        Compact alternative for type() with more options
        - special keys and options are coded as #XN. or #X+ or #X-
        where X is a refrence for a special key and N is an optional repeat factor
        A modifier key as #X. modifies the next following key
        the trailing . ends the special key, the + (press and hold) or - (release) does the same,
        but signals press-and-hold or release additionally.
        except #W / #w all special keys are not case-sensitive
        a #wn. inserts a wait of n millisecs or n secs if n less than 60
        a #Wn. sets the type delay for the following keys (must be > 60 and denotes millisecs) - otherwise taken as normal wait
        Example: wait 2 secs then type CMD/CTRL - N then wait 1 sec then type DOWN 3 times
        Windows/Linux: write("#w2.#C.n#W1.#d3.")
        Mac: write("#w2.#M.n#W1.#D3.")
        for more details about the special key codes and examples consult the docs
        Parameters:
        text - a coded text interpreted as a series of key actions (press/hold/release)
        Returns:
        0 for success 1 otherwise

      • type

        public int type​(java.lang.String text)
        enters the given text one character/key after another using keyDown/keyUp.
        about the usable Key constants see keyDown(keys)
        Class Key only provides a subset of a US-QWERTY PC keyboard layout
        the text is entered at the current position of the focus/carret
        Parameters:
        text - containing characters and/or Key constants
        Returns:
        1 if possible, 0 otherwise

      • type

        public int type​(java.lang.String text,
                int modifiers)
        enters the given text one character/key after another using keyDown/keyUp.
        while holding down the given modifier keys
        about the usable Key constants see keyDown(keys)
        Class Key only provides a subset of a US-QWERTY PC keyboard layout
        the text is entered at the current position of the focus/carret
        Parameters:
        text - containing characters and/or Key constants
        modifiers - constants according to class KeyModifiers
        Returns:
        1 if possible, 0 otherwise

      • type

        public int type​(java.lang.String text,
                java.lang.String modifiers)
        enters the given text one character/key after another using keyDown/keyUp.
        while holding down the given modifier keys
        about the usable Key constants see keyDown(keys)
        Class Key only provides a subset of a US-QWERTY PC keyboard layout
        the text is entered at the current position of the focus/carret
        Parameters:
        text - containing characters and/or Key constants
        modifiers - constants according to class Key - combine using +
        Returns:
        1 if possible, 0 otherwise

      • type

        public <PFRML> int type​(PFRML target,
                        java.lang.String text)
                 throws FindFailed
        first does a click(target) at the given target position to gain focus/carret.
        then enters the given text one character/key after another using keyDown/keyUp
        about the usable Key constants see keyDown(keys)
        Class Key only provides a subset of a US-QWERTY PC keyboard layout
        Type Parameters:
        PFRML - Pattern, Filename, Text, Region, Match or Location
        Parameters:
        target - Pattern, Filename, Text, Region, Match or Location
        text - containing characters and/or Key constants
        Returns:
        1 if possible, 0 otherwise
        Throws:
        FindFailed - if not found

      • type

        public <PFRML> int type​(PFRML target,
                        java.lang.String text,
                        int modifiers)
                 throws FindFailed
        first does a click(target) at the given target position to gain focus/carret
        enters the given text one character/key after another using keyDown/keyUp
        while holding down the given modifier keys
        about the usable Key constants see keyDown(keys)
        Class Key only provides a subset of a US-QWERTY PC keyboard layout
        Type Parameters:
        PFRML - Pattern, Filename, Text, Region, Match or Location
        Parameters:
        target - Pattern, Filename, Text, Region, Match or Location
        text - containing characters and/or Key constants
        modifiers - constants according to class KeyModifiers
        Returns:
        1 if possible, 0 otherwise
        Throws:
        FindFailed - if not found

      • type

        public <PFRML> int type​(PFRML target,
                        java.lang.String text,
                        java.lang.String modifiers)
                 throws FindFailed
        first does a click(target) at the given target position to gain focus/carret
        enters the given text one character/key after another using keyDown/keyUp
        while holding down the given modifier keys
        about the usable Key constants see keyDown(keys)
        Class Key only provides a subset of a US-QWERTY PC keyboard layout
        Type Parameters:
        PFRML - Pattern, Filename, Text, Region, Match or Location
        Parameters:
        target - Pattern, Filename, Text, Region, Match or Location
        text - containing characters and/or Key constants
        modifiers - constants according to class Key - combine using +
        Returns:
        1 if possible, 0 otherwise
        Throws:
        FindFailed - if not found

      • delayType

        public void delayType​(int millisecs)
        time in milliseconds to delay between each character at next type only (max 1000)
        Parameters:
        millisecs - value

      • keyDown

        public void keyDown​(int keycode)
        press and hold the given key use a constant from java.awt.event.KeyEvent which might be special in the current machine/system environment
        Parameters:
        keycode - Java KeyCode

      • keyDown

        public void keyDown​(java.lang.String keys)
        press and hold the given keys including modifier keys.
        use the key constants defined in class Key,
        which only provides a subset of a US-QWERTY PC keyboard layout
        might be mixed with simple characters
        use + to concatenate Key constants
        Parameters:
        keys - valid keys

      • keyUp

        public void keyUp()
        release all currently pressed keys

      • keyUp

        public void keyUp​(int keycode)
        release the given keys (see keyDown(keycode) )
        Parameters:
        keycode - Java KeyCode

      • keyUp

        public void keyUp​(java.lang.String keys)
        release the given keys (see keyDown(keys) )
        Parameters:
        keys - valid keys

      • paste

        public int paste​(java.lang.String text)
        pastes the text at the current position of the focus/carret.
        using the clipboard and strg/ctrl/cmd-v (paste keyboard shortcut)
        Parameters:
        text - a string, which might contain unicode characters
        Returns:
        0 if possible, 1 otherwise

      • paste

        public <PFRML> int paste​(PFRML target,
                         java.lang.String text)
                  throws FindFailed
        first does a click(target) at the given target position to gain focus/carret.
        and then pastes the text
        using the clipboard and strg/ctrl/cmd-v (paste keyboard shortcut)
        Type Parameters:
        PFRML - Pattern, Filename, Text, Region, Match or Location target
        Parameters:
        target - Pattern, Filename, Text, Region, Match or Location
        text - a string, which might contain unicode characters
        Returns:
        1 if possible, 0 otherwise
        Throws:
        FindFailed - if not found

      • aInput

        public void aInput​(java.lang.String text)

      • aKey

        public void aKey​(int key)

      • aSwipe

        public <PFRML> void aSwipe​(PFRML from,
                           PFRML to)
                    throws FindFailed
        Throws:
        FindFailed

      • aSwipeUp

        public void aSwipeUp()

      • aSwipeDown

        public void aSwipeDown()

      • aSwipeLeft

        public void aSwipeLeft()

      • aSwipeRight

        public void aSwipeRight()

      • saveCapture

        public java.lang.String saveCapture​(java.lang.Object... args)

      • getLastScreenImage

        public ScreenImage getLastScreenImage()
        get the last image taken on this regions screen
        Returns:
        the stored ScreenImage

      • getLastScreenImageFile

        public java.lang.String getLastScreenImageFile()
                                        throws java.io.IOException
        stores the lastScreenImage in the current bundle path with a created unique name
        Returns:
        the absolute file name
        Throws:
        java.io.IOException - if not possible

      • getLastScreenImageFile

        public java.lang.String getLastScreenImageFile​(java.lang.String name)
                                        throws java.io.IOException
        stores the lastScreenImage in the current bundle path with the given name
        Parameters:
        name - file name (.png is added if not there)
        Returns:
        the absolute file name
        Throws:
        java.io.IOException - if not possible

      • getLastScreenImageFile

        public java.lang.String getLastScreenImageFile​(java.lang.String path,
                                               java.lang.String name)
                                        throws java.io.IOException
        stores the lastScreenImage in the given path with the given name
        Parameters:
        path - path to use
        name - file name (.png is added if not there)
        Returns:
        the absolute file name
        Throws:
        java.io.IOException - if not possible

      • saveLastScreenImage

        public void saveLastScreenImage()