Package org.sikuli.script

Class Region

  • Direct Known Subclasses:
    ADBScreen, Match, Screen, VNCScreen
    public class Region
extends Element
    A Region is a rectengular 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

    • Constructor Summary

      Constructors 
      Modifier Constructor Description
      protected Region()
      internal use only, used for new Screen objects to get the Region behavior
      protected Region​(boolean isScreenUnion)
      internal use only, used for new Screen objects to get the Region behavior
        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, IScreen parentScreen)
      Create a region with the provided coordinate / size and screen
        Region​(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
      the new region extends to the top screen border
      use grow() to include the current region
      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
      might be off current screen
      Region add​(int l, int r, int t, int b)
      resize the region using the given padding values
      might be negative
      Region add​(Location loc)
      extend the region, so it contains the given point
      but only the part inside the current screen
      Region add​(Region r)
      extend the region, so it contains the given region
      but only the part inside the current screen
      void aInput​(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
      the new region extends to the bottom screen border
      use grow() to include the current region
      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
      Location belowAt()  
      Location belowAt​(int offset)
      positive offset goes towards bottom of screen
      might be off current screen
      Location checkMatch()  
      int click()
      left click at the region's last successful match
      use center if no lastMatch
      if region is a match: click targetOffset
      <PFRML> int click​(PFRML target)
      left 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 click​(PFRML target, Integer modifiers)
      left 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
      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​(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, IScreen scr)
      Create a region with the provided top left corner and size
      static Region create​(Rectangle r)
      Create a region from a Rectangle
      protected static Region create​(Rectangle r, IScreen parentScreen)
      Create a region from a Rectangle on a given Screen
      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
      as specified with x y
      0 0 top left
      0 1 bottom left
      1 0 top right
      1 1 bottom right
      static Region create​(Region r)
      Create a region from another region
      including the region's settings
      void delayClick​(int millisecs)
      time in milliseconds to delay between button down/up at next click only (max 1000)
      void delayType​(int millisecs)
      time in milliseconds to delay between each character at next type only (max 1000)
      protected Region doHighlight​(double secs, String color)  
      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
      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 doubleClick​(PFRML target, Integer modifiers)
      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
      <PFRML> int drag​(PFRML target)
      Prepare a drag action: move mouse to given target
      press and hold left mouse button
      wait Settings.DelayAfterDrag
      <PFRML> int dragDrop​(PFRML target)
      Drag from region's last match and drop at given target
      applying Settings.DelayAfterDrag and DelayBeforeDrop
      using left mouse button
      <PFRML> int dragDrop​(PFRML t1, PFRML t2)
      Drag from a position and drop to another using left mouse button
      applying Settings.DelayAfterDrag and DelayBeforeDrop
      <PFRML> int dropAt​(PFRML target)
      finalize a drag action with a drop: move mouse to given target
      wait Settings.DelayBeforeDrop
      before releasing the left mouse button
      <PSI> Match exists​(PSI target)
      Check if target exists (with the default autoWaitTimeout), does not raise FindFailed
      <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
      Match existsText​(String text)  
      Match existsText​(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> Iterator<Match> findAll​(PSI target)
      finds all occurences of the given Pattern, String or Image in the region and returns an Iterator of Matches.
      <PSI> List<Match> findAllByColumn​(PSI target)  
      <PSI> List<Match> findAllByRow​(PSI target)  
      <PSI> List<Match> findAllList​(PSI target)  
      List<Match> findAllText​(String text)  
      List<Match> findAny​(Object... args)  
      List<Match> findAnyList​(List<Object> pList)  
      Match findBest​(Object... args)  
      Match findBestList​(List<Object> pList)  
      Match findText​(String text)  
      Region get​(int part)  
      <PSI> List<Match> getAll​(PSI target)  
      double getAutoWaitTimeout()
      current setting for this region (see setAutoWaitTimeout)
      Location getBottomLeft()  
      Location getBottomRight()  
      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
      Location getCenter()  
      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
      Region getCol​(int c, int n)
      divide the region in n columns and select column c as new Region
      int getCols()  
      int getColW()  
      static Region getDefaultInstance4py()  
      ObserveEvent getEvent​(String name)
      the event is removed from the list
      ObserveEvent[] getEvents()
      the region's events are removed from the list
      protected static Region getFakeRegion()  
      FindFailedResponse getFindFailedResponse()  
      Image getImage()  
      Region getInset​(Region inset)  
      ScreenImage getLastScreenImage()
      get the last image taken on this regions screen
      String getLastScreenImageFile()
      stores the lastScreenImage in the current bundle path with a created unique name
      String getLastScreenImageFile​(String name)
      stores the lastScreenImage in the current bundle path with the given name
      String getLastScreenImageFile​(String path, String name)
      stores the lastScreenImage in the given path with the given name
      protected <PSIMRL> Location getLocationFromTarget​(PSIMRL target)  
      Observer getObserver()  
      float getObserveScanRate()  
      Rectangle getRect()  
      protected static Rectangle getRectangle​(Rectangle rect, int part)  
      int getRepeatWaitTime()
      INTERNAL USE: Observe
      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
      negative counts reverse from the end (last is -1)
      values outside range are 0 or last respectively
      Region getRow​(int r, int n)  
      int getRowH()  
      int getRows()  
      IScreen getScreen()  
      IScreen getScreenContaining()
      Deprecated.
      Only for compatibility, to get the screen containing this region, use getScreen()
      Location getTarget()
      convenience method
      boolean getThrowException()
      current setting setThrowException(boolean)
      Location getTopLeft()  
      Location getTopRight()  
      float getWaitScanRate()  
      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. negative values go inside (shrink)
      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
      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
      <PSI> boolean has​(PSI target)
      Check if target exists
      - does not raise FindFailed - like exists(target, 0) but returns true/false
      - which means only one search
      - no wait for target to appear
      - intended to be used in logical expressions
      - use getLastMatch() to get the match if found
      <PSI> boolean has​(PSI target, double timeout)
      Check if target appears within the specified time
      - does not raise FindFailed - like exists(target, timeout) but returns true/false
      - intended to be used in logical expressions
      - use getLastMatch() to get the match if found
      boolean hasEvents()  
      boolean hasObserver()
      evaluate if at least one event observer is defined for this region (the observer need not be running)
      boolean hasText​(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, 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​(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)
      Region highlight4py​(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​(String color)
      Switch on the regions highlight with given color
      int hover()
      move the mouse pointer to region's last successful match
      use center if no lastMatch
      if region is a match: move to targetOffset
      same as mouseMove
      <PFRML> int hover​(PFRML target)
      move the mouse pointer to the given target location
      same as mouseMove
      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
      void initScreen​(IScreen iscr)
      INTERNAL USE
      Region inside()
      Deprecated.
      only for backward compatibility
      void internalUseOnlyHighlightReset()
      INTERNAL USE ONLY
      Region intersection​(Region ir)
      create a region that is the intersection of the given regions
      boolean isObserving()  
      boolean isOtherScreen()
      INTERNAL USE: checks wether this region belongs to a non-Desktop screen
      boolean isRasterValid()
      Can be used to check, wether the Region currently has a valid raster
      boolean isValid()
      Check wether thie Region is contained by any of the available screens
      boolean isVirtual()
      INTERNAL USE - EXPERIMENTAL if true: this region is not bound to any screen
      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​(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
      void keyUp()
      release all currently pressed keys
      void keyUp​(int keycode)
      release the given keys (see keyDown(keycode) )
      void keyUp​(String keys)
      release the given keys (see keyDown(keys) )
      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
      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
      Location leftAt()  
      Location leftAt​(int offset)
      negative offset goes to the left
      might be off current screen
      static Region make4py​(ArrayList args)  
      Region morphTo​(Region r)
      Deprecated.
      to be like AWT Rectangle API use setRect() instead
      void mouseDown​(int buttons)
      press and hold the specified buttons - use + to combine Button.LEFT left mouse button Button.MIDDLE middle mouse button Button.RIGHT right mouse button
      int mouseMove()
      move the mouse pointer to the region's last successful match
      same as hover
      int mouseMove​(int xoff, int yoff)
      move the mouse from the current position to the offset position given by the parameters
      <PFRML> int mouseMove​(PFRML target)
      move the mouse pointer to the given target location
      same as hover
      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
      void mouseUp()
      release all currently held buttons
      void mouseUp​(int buttons)
      release the specified mouse buttons (see mouseDown) if buttons==0, all currently held buttons are released
      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 USE 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​(Object whatever)
      create region with same size at top left corner offset
      <PSI> 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 @{link Observing}
      for details about APPEAR/VANISH/CHANGE events: ObserveEvent
      <PSI> String onAppear​(PSI target, 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
      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 @{link Observing}
      minimum size of changes used: Settings.ObserveMinChangedPixels for details about APPEAR/VANISH/CHANGE events: ObserveEvent
      String onChange​(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 @{link Observing}
      for details about APPEAR/VANISH/CHANGE events: ObserveEvent
      String onChange​(Integer threshold, 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
      String onChange​(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
      <PSI> 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 @{link Observing}
      for details about APPEAR/VANISH/CHANGE events: ObserveEvent
      <PSI> String onVanish​(PSI target, 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
      int paste​(String text)
      pastes the text at the current position of the focus/carret
      using the clipboard and strg/ctrl/cmd-v (paste keyboard shortcut)
      <PFRML> int paste​(PFRML target, String text)
      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)
      protected Rectangle regionOnScreen​(IScreen screen)
      Checks if the Screen contains the Region.
      protected List<Match> relocate​(List<Match> matches)  
      protected Match relocate​(Match match)  
      void resetFindFailedResponse()
      reset to default setFindFailedResponse(FindFailedResponse)
      void resetScreens()
      synonym for resetMonitors
      void resetThrowException()
      reset to default setThrowException(boolean)
      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
      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
      Location rightAt()
      point middle on right edge
      Location rightAt​(int offset)
      positive offset goes to the right. might be off current screen
      int rightClick()
      right click at the region's last successful match
      use center if no lastMatch
      if region is a match: click targetOffset
      <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, 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
      String saveCapture​(Object... args)  
      void saveLastScreenImage()  
      void setActive​(String name)
      set the observer with the given name active (checked while observing)
      void setAutoWaitTimeout​(double sec)
      the time in seconds a find operation should wait
      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 setCenter​(Location loc)
      Moves the region to the area, whose center is the given location
      Region setCols​(int n)
      store info: this region is divided horizontally into n even columns
      a preparation for using getCol()
      void setFindFailedHandler​(Object handler)  
      void setFindFailedResponse​(FindFailedResponse response)
      FindFailedResponse.
      ABORT - abort script on FindFailed
      SKIP - ignore FindFailed
      PROMPT - display prompt on FindFailed to let user decide how to proceed
      RETRY - continue to wait for appearence after FindFailed
      HANDLE - call a handler on exception setFindFailedHandler(Object)
      default: ABORT
      see also: setThrowException(boolean)
      Region setH​(int H)  
      void setInactive​(String name)
      set the observer with the given name inactive (not checked while observing)
      Region setLocation​(Location loc)
      set the regions position
      this might move the region even to another screen
      void setObserveScanRate​(float observeScanRate)
      set the regions individual ObserveScanRate
      void setOtherScreen()
      INTERNAL USE: flags this region as belonging to a non-Desktop screen
      Region setOtherScreen​(IScreen aScreen)
      INTERNAL: flags this region as belonging to a non-Desktop screen
      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
      Region setRect​(int X, int Y, int W, int H)
      set the regions position/size
      this might move the region even to another screen
      Region setRect​(Rectangle r)
      set the regions position/size
      this might move the region even to another screen
      Region setRect​(Region r)
      set the regions position/size
      this might move the region even to another screen
      void setRepeatWaitTime​(int time)
      INTERNAL USE: Observe set the regions individual WaitForVanish
      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
      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.
      void setROI​(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.
      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.
      Region setRows​(int n)
      store info: this region is divided vertically into n even rows
      a preparation for using getRow()
      protected Region setScreen​(int id)
      Sets a new Screen for this region.
      protected Region setScreen​(IScreen scr)
      Sets a new Screen for this region.
      Region setSize​(int W, int H)  
      void setThrowException​(boolean flag)
      true - should throw FindFailed if not found in this region
      false - do not abort script on FindFailed (might lead to NPE's later)
      default: Settings.ThrowException
      sideEffects: setFindFailedResponse(FindFailedResponse) true:ABORT, false:SKIP
      see also: setFindFailedResponse(FindFailedResponse)
      and: setFindFailedHandler(Object)
      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 setVirtual​(boolean state)
      INTERNAL USE - EXPERIMENTAL
      Region setW​(int W)  
      void setWaitScanRate​(float waitScanRate)
      set the regions individual WaitScanRate
      Region setX​(int X)
      set the horizontal position of the top-left corner
      Region setY​(int Y)  
      void showScreens()
      synonym for showMonitors
      void stopObserver()
      stops a running observer
      void stopObserver​(String message)
      stops a running observer printing an info message
      protected Match toGlobalCoord​(Match m)
      used in Observer.callChangeObserving, Finder.next to adjust region relative coordinates of matches to screen coordinates
      String toString()
      String toStringShort()  
      int type​(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
      int type​(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
      int type​(String text, String modifiers)
      enters the given text one character/key after another using
      <PFRML> int type​(PFRML target, String text)
      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
      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, 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, String text, 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
      Region union​(Region ur)
      create a new region containing both regions
      <PSI> Region unionAll​(PSI target)  
      Region unionAny​(Object... targets)  
      Region unionAnyList​(List<Object> targets)  
      static Region virtual​(Rectangle rect)
      INTERNAL USE - EXPERIMENTAL if true: this region is not bound to any screen
      void wait​(double timeout)
      WARNING: wait(long timeout) is taken by Java Object as final.
      <PSI> Match wait​(PSI target)
      Waits for the Pattern, String or Image to appear until the AutoWaitTimeout value is exceeded.
      <PSI> Match wait​(PSI target, double timeout)
      Waits for the Pattern, String or Image to appear or timeout (in second) is passed
      List<Match> waitAny​(double time, Object... args)  
      List<Match> waitAnyList​(double time, List<Object> pList)  
      Match waitBest​(double time, Object... args)  
      Match waitBestList​(double time, List<Object> pList)  
      Match waitT​(String text)  
      Match waitT​(String text, double timeout)  
      Match waitText​(String text)  
      Match waitText​(String text, double timeout)  
      <PSI> boolean waitVanish​(PSI target)
      waits until target vanishes or timeout (in seconds) is passed (AutoWaitTimeout)
      <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
      the given steps in the given direction:
      Button.WHEEL_DOWN, Button.WHEEL_UP
      <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 stepDelay)
      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
      int write​(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.

    • Constructor Detail

      • Region

        protected Region()
        internal use only, used for new Screen objects to get the Region behavior

      • Region

        protected Region​(boolean isScreenUnion)
        internal use only, used for new Screen objects to get the Region behavior

      • 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,
              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​(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

      • getDefaultInstance4py

        public static Region getDefaultInstance4py()

      • setX

        public Region setX​(int X)
        set the horizontal position of the top-left corner
        Parameters:
        X - new x-value of top-left corner
        Returns:
        this Region

      • setY

        public Region setY​(int Y)
        Parameters:
        Y - new y position of top left corner
        Returns:
        this Region

      • setW

        public Region setW​(int W)
        Parameters:
        W - new width
        Returns:
        this Region

      • setH

        public Region setH​(int H)
        Parameters:
        H - new height
        Returns:
        this Region

      • setFindFailedResponse

        public void setFindFailedResponse​(FindFailedResponse response)
        FindFailedResponse.
        ABORT - abort script on FindFailed
        SKIP - ignore FindFailed
        PROMPT - display prompt on FindFailed to let user decide how to proceed
        RETRY - continue to wait for appearence after FindFailed
        HANDLE - call a handler on exception setFindFailedHandler(Object)
        default: ABORT
        see also: setThrowException(boolean)
        Parameters:
        response - FindFailed

      • setFindFailedHandler

        public void setFindFailedHandler​(Object handler)

      • setAutoWaitTimeout

        public void setAutoWaitTimeout​(double sec)
        the time in seconds a find operation should wait

        for the appearence of the target in this region
        initial value is the global AutoWaitTimeout setting at time of Region creation

        Parameters:
        sec - seconds

      • getAutoWaitTimeout

        public double getAutoWaitTimeout()
        current setting for this region (see setAutoWaitTimeout)
        Returns:
        value of seconds

      • getWaitScanRate

        public float getWaitScanRate()
        Returns:
        the regions current WaitScanRate

      • setWaitScanRate

        public void setWaitScanRate​(float waitScanRate)
        set the regions individual WaitScanRate
        Parameters:
        waitScanRate - decimal number

      • getObserveScanRate

        public float getObserveScanRate()
        Returns:
        the regions current ObserveScanRate

      • setObserveScanRate

        public void setObserveScanRate​(float observeScanRate)
        set the regions individual ObserveScanRate
        Parameters:
        observeScanRate - decimal number

      • getRepeatWaitTime

        public int getRepeatWaitTime()
        INTERNAL USE: Observe
        Returns:
        the regions current RepeatWaitTime time in seconds

      • setRepeatWaitTime

        public void setRepeatWaitTime​(int time)
        INTERNAL USE: Observe set the regions individual WaitForVanish
        Parameters:
        time - in seconds

      • getFakeRegion

        protected static Region getFakeRegion()

      • toString

        public String toString()
        Overrides:
        toString in class Object
        Returns:
        the description

      • toStringShort

        public String toStringShort()
        Returns:
        a compact description

      • initScreen

        public void initScreen​(IScreen iscr)
        INTERNAL USE
        Parameters:
        iscr - screen

      • virtual

        public static Region virtual​(Rectangle rect)
        INTERNAL USE - EXPERIMENTAL if true: this region is not bound to any screen
        Parameters:
        rect - rectangle
        Returns:
        the current state

      • isVirtual

        public boolean isVirtual()
        INTERNAL USE - EXPERIMENTAL if true: this region is not bound to any screen
        Returns:
        the current state

      • setVirtual

        public void setVirtual​(boolean state)
        INTERNAL USE - EXPERIMENTAL
        Parameters:
        state - if true: this region is not bound to any screen

      • isOtherScreen

        public boolean isOtherScreen()
        INTERNAL USE: checks wether this region belongs to a non-Desktop screen
        Returns:
        true/false

      • setOtherScreen

        public void setOtherScreen()
        INTERNAL USE: flags this region as belonging to a non-Desktop screen

      • setOtherScreen

        public Region setOtherScreen​(IScreen aScreen)
        INTERNAL: flags this region as belonging to a non-Desktop screen
        Parameters:
        aScreen - screen
        Returns:
        this Region

      • regionOnScreen

        protected Rectangle regionOnScreen​(IScreen screen)
        Checks if the Screen contains the Region.
        Parameters:
        screen - The Screen in which the Region might be
        Returns:
        True, if the Region is on the Screen. False if the Region is not inside the Screen

      • isValid

        public boolean isValid()
        Check wether thie Region is contained by any of the available screens
        Returns:
        true if yes, false otherwise

      • 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,
                            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​(Rectangle r)
        Create a region from a Rectangle
        Parameters:
        r - the Rectangle
        Returns:
        the new region

      • create

        protected static Region create​(Rectangle r,
                               IScreen parentScreen)
        Create a region from a Rectangle on a given Screen
        Parameters:
        r - the Rectangle
        parentScreen - the new parent screen
        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

      • 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​(IScreen screen)
        new region with same offset to current screen's top left on given screen
        Parameters:
        screen - new parent screen
        Returns:
        new region

      • toGlobalCoord

        protected Match toGlobalCoord​(Match m)
        used in Observer.callChangeObserving, Finder.next to adjust region relative coordinates of matches to screen coordinates
        Parameters:
        m -
        Returns:
        the modified match

      • getScreen

        public IScreen getScreen()
        Returns:
        the Screen object containing the region

      • getScreenContaining

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

      • setScreen

        protected Region setScreen​(IScreen scr)
        Sets a new Screen for this region.
        Parameters:
        scr - the containing screen object
        Returns:
        the region itself

      • setScreen

        protected Region setScreen​(int id)
        Sets a new Screen for this region.
        Parameters:
        id - the containing screen object's id
        Returns:
        the region itself

      • showScreens

        public void showScreens()
        synonym for showMonitors

      • resetScreens

        public void resetScreens()
        synonym for resetMonitors

      • getCenter

        public Location getCenter()
        Returns:
        the center pixel location of the region

      • getTarget

        public Location getTarget()
        convenience method
        Returns:
        the region's center

      • setCenter

        public Region setCenter​(Location loc)
        Moves the region to the area, whose center is the given location
        Parameters:
        loc - the location which is the new center of the region
        Returns:
        the region itself

      • 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

      • setSize

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

      • getRect

        public Rectangle getRect()
        Returns:
        the AWT Rectangle of the region

      • setRect

        public Region setRect​(Rectangle r)
        set the regions position/size
        this might move the region even to another screen
        Parameters:
        r - the AWT Rectangle to use for position/size
        Returns:
        the region itself

      • setRect

        public Region setRect​(int X,
                      int Y,
                      int W,
                      int H)
        set the regions position/size
        this might move the region even to another screen
        Parameters:
        X - new x of top left corner
        Y - new y of top left corner
        W - new width
        H - new height
        Returns:
        the region itself

      • setRect

        public Region setRect​(Region r)
        set the regions position/size
        this might move the region even to another screen
        Parameters:
        r - the region to use for position/size
        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​(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

      • saveCapture

        public String saveCapture​(Object... args)

      • getLastScreenImage

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

      • getLastScreenImageFile

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

      • getLastScreenImageFile

        public String getLastScreenImageFile​(String name)
                              throws 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:
        IOException - if not possible

      • getLastScreenImageFile

        public String getLastScreenImageFile​(String path,
                                     String name)
                              throws 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:
        IOException - if not possible

      • saveLastScreenImage

        public void saveLastScreenImage()

      • contains

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

      • 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

      • offset

        public Region offset​(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

      • 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

      • 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

      • 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

      • 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

      • 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

      • 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

      • 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

      • 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

      • union

        public Region union​(Region ur)
        create a new region containing both regions
        Parameters:
        ur - region to unite with
        Returns:
        the new region

      • intersection

        public Region intersection​(Region ir)
        create a region that is the intersection of the given regions
        Parameters:
        ir - the region to intersect with like AWT Rectangle API
        Returns:
        the new region

      • get

        public Region get​(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

      • highlight4py

        public Region highlight4py​(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 - valuaes as above
        Returns:
        this

      • internalUseOnlyHighlightReset

        public void internalUseOnlyHighlightReset()
        INTERNAL USE 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​(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​(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,
                        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

      • doHighlight

        protected Region doHighlight​(double secs,
                             String color)

      • wait

        public void wait​(double timeout)
        WARNING: wait(long timeout) is taken by Java Object as final. This method catches any interruptedExceptions
        Parameters:
        timeout - The time to wait

      • 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
        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

      • wait

        public <PSI> Match wait​(PSI target)
                 throws FindFailed
        Waits for the Pattern, String or Image to appear until the AutoWaitTimeout value is exceeded.
        Type Parameters:
        PSI - Pattern, String or Image
        Parameters:
        target - The target to search for
        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 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
        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)

      • exists

        public <PSI> Match exists​(PSI target)
        Check if target exists (with the default autoWaitTimeout), does not raise FindFailed
        Type Parameters:
        PSI - Pattern, String or Image
        Parameters:
        target - Pattern, String or Image
        Returns:
        the match (null if not found or image file missing)

      • has

        public <PSI> boolean has​(PSI target)
        Check if target exists
        - does not raise FindFailed - like exists(target, 0) but returns true/false
        - which means only one search
        - no wait for target to appear
        - intended to be used in logical expressions
        - use getLastMatch() to get the match if found
        Type Parameters:
        PSI - Pattern, String or Image
        Parameters:
        target - Pattern, String or Image
        Returns:
        true if found, false otherwise

      • has

        public <PSI> boolean has​(PSI target,
                         double timeout)
        Check if target appears within the specified time
        - does not raise FindFailed - like exists(target, timeout) but returns true/false
        - intended to be used in logical expressions
        - use getLastMatch() to get the match if found
        Type Parameters:
        PSI - Pattern, String or Image
        Parameters:
        target - The target to search for
        timeout - Timeout in seconds
        Returns:
        true if found, false otherwise

      • waitVanish

        public <PSI> boolean waitVanish​(PSI target,
                                double timeout)
        waits until target vanishes or timeout (in seconds) is passed
        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.

      • waitVanish

        public <PSI> boolean waitVanish​(PSI target)
        waits until target vanishes or timeout (in seconds) is passed (AutoWaitTimeout)
        Type Parameters:
        PSI - Pattern, String or Image
        Parameters:
        target - The target to wait for it to vanish
        Returns:
        true if the target vanishes, otherwise returns false.

      • findAll

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

      • getAll

        public <PSI> List<Match> getAll​(PSI target)

      • unionAll

        public <PSI> Region unionAll​(PSI target)

      • findAllList

        public <PSI> List<Match> findAllList​(PSI target)

      • findAllByRow

        public <PSI> List<Match> findAllByRow​(PSI target)

      • findAllByColumn

        public <PSI> List<Match> findAllByColumn​(PSI target)

      • waitBest

        public Match waitBest​(double time,
                      Object... args)

      • waitBestList

        public Match waitBestList​(double time,
                          List<Object> pList)

      • existsText

        public Match existsText​(String text,
                        double timeout)

      • getObserver

        public 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​(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​(String name)
        set the observer with the given name inactive (not checked while observing)
        Parameters:
        name - observers name

      • setActive

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

      • onAppear

        public <PSI> String onAppear​(PSI target,
                             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> 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 @{link 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> String onVanish​(PSI target,
                             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> 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 @{link 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 String onChange​(Integer threshold,
                       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 String onChange​(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 @{link 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 String onChange​(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 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 @{link Observing}
        minimum size of changes used: Settings.ObserveMinChangedPixels for details about APPEAR/VANISH/CHANGE events: ObserveEvent
        Returns:
        the event's name

      • 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 USE 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​(String message)
        stops a running observer printing an info message
        Parameters:
        message - text

      • checkMatch

        public Location checkMatch()

      • hover

        public int hover()
        move the mouse pointer to region's last successful match
        use center if no lastMatch
        if region is a match: move to targetOffset
        same as mouseMove
        Returns:
        1 if possible, 0 otherwise

      • hover

        public <PFRML> int hover​(PFRML target)
                  throws FindFailed
        move the mouse pointer to the given target location
        same as mouseMove
        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 - to search: 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

      • click

        public int click()
        left 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

      • click

        public <PFRML> int click​(PFRML target)
                  throws FindFailed
        left 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 - to search: 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

      • click

        public <PFRML> int click​(PFRML target,
                         Integer modifiers)
                  throws FindFailed
        left 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 - to search: 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

      • 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,
                               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,
                              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

      • delayClick

        public void delayClick​(int millisecs)
        time in milliseconds to delay between button down/up at next click only (max 1000)
        Parameters:
        millisecs - value

      • 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

      • mouseDown

        public void mouseDown​(int buttons)
        press and hold the specified buttons - use + to combine Button.LEFT left mouse button Button.MIDDLE middle mouse button Button.RIGHT right mouse button
        Parameters:
        buttons - spec

      • mouseUp

        public void mouseUp()
        release all currently held buttons

      • mouseUp

        public void mouseUp​(int buttons)
        release the specified mouse buttons (see mouseDown) if buttons==0, all currently held buttons are released
        Parameters:
        buttons - spec

      • mouseMove

        public int mouseMove()
        move the mouse pointer to the region's last successful match
        same as hover
        Returns:
        1 if possible, 0 otherwise

      • mouseMove

        public <PFRML> int mouseMove​(PFRML target)
                      throws FindFailed
        move the mouse pointer to the given target location
        same as hover
        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

      • mouseMove

        public int mouseMove​(int xoff,
                     int yoff)
        move the mouse from the current position to the offset position given by the parameters
        Parameters:
        xoff - horizontal offset (< 0 left, > 0 right)
        yoff - vertical offset (< 0 up, > 0 down)
        Returns:
        1 if possible, 0 otherwise

      • 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 <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,
                         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
        stepDelay - number of miliseconds to wait when incrementing the step value
        Returns:
        1 if possible, 0 otherwise
        Throws:
        FindFailed - if the Find operation failed

      • 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​(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​(String keys)
        release the given keys (see keyDown(keys) )
        Parameters:
        keys - valid keys

      • write

        public int write​(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​(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​(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​(String text,
                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,
                        String text)
                 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
        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,
                        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,
                        String text,
                        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

      • paste

        public int paste​(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,
                         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​(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()