This is an automated email from the git hooks/post-receive script. pini pushed a commit to tag upstream/1.1.0_beta1 in repository sikuli.
commit 0c272a01b7d5634ed46ff1d25f5f6a1adfcb6f18 Author: Raimund Hocke <[email protected]> Date: Tue Feb 25 11:47:48 2014 +0100 revising java docs --- API/src/main/java/org/sikuli/script/Region.java | 93 +++++++++++++++++++++- .../main/java/org/sikuli/script/SikuliEvent.java | 67 ++++++++++++++-- .../java/org/sikuli/script/SikuliEventChange.java | 6 +- .../java/org/sikuli/ide/EditorViewFactory.java | 50 +++++++----- 4 files changed, 183 insertions(+), 33 deletions(-) diff --git a/API/src/main/java/org/sikuli/script/Region.java b/API/src/main/java/org/sikuli/script/Region.java index 592192f..9fdd479 100755 --- a/API/src/main/java/org/sikuli/script/Region.java +++ b/API/src/main/java/org/sikuli/script/Region.java @@ -2467,46 +2467,95 @@ public class Region { return evtMgr; } + /** + * + * @return true if an observer is active for this region + */ public boolean isObserving() { return observing; } + /** + * 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: {@link SikuliEventObserver} + * for details about APPEAR/VANISH/CHANGE events: {@link SikuliEvent} + * @param target + * @param observer + * @return + */ public <PSI> String onAppear(PSI target, Object observer) { return onAppearDo(target, observer); } + /** + *INTERNAL USE ONLY: for use with scripting API bridges + */ public <PSI> String onAppearJ(PSI target, Object observer) { return onAppearDo(target, observer); } - public <PSI> String onAppearDo(PSI target, Object observer) { + private <PSI> String onAppearDo(PSI target, Object observer) { String name = Observer.add(this, (ObserverCallBack) observer, SikuliEvent.Type.APPEAR); getEventManager().addAppearObserver(target, (SikuliEventObserver) observer, name); return name; } + /** + * 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: {@link SikuliEventObserver} + * for details about APPEAR/VANISH/CHANGE events: {@link SikuliEvent} + * @param target + * @param observer + * @return + */ public <PSI> String onVanish(PSI target, Object observer) { return onVanishDo(target, observer); } + /** + *INTERNAL USE ONLY: for use with scripting API bridges + */ public <PSI> String onVanishJ(PSI target, Object observer) { return onVanishDo(target, observer); } - public <PSI> String onVanishDo(PSI target, Object observer) { + private <PSI> String onVanishDo(PSI target, Object observer) { String name = Observer.add(this, (ObserverCallBack) observer, SikuliEvent.Type.VANISH); getEventManager().addVanishObserver(target, (SikuliEventObserver) observer, name); return name; } + /** + * 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: {@link SikuliEventObserver} + * for details about APPEAR/VANISH/CHANGE events: {@link SikuliEvent} + * @param threshold minimum size of changes (rectangle threshhold x threshold) + * @param observer + * @return + */ public String onChange(int threshold, Object observer) { return onChangeDo(threshold, observer); } + /** + * a subsequently started observer in this region should wait for changes in the region + * and notify the given observer about this event <br /> + * minimum size of changes used: Settings.ObserveMinChangedPixels + * for details about the observe event handler: {@link SikuliEventObserver} + * for details about APPEAR/VANISH/CHANGE events: {@link SikuliEvent} + * @param observer + * @return + */ public String onChange(Object observer) { return onChangeDo(rows, observer); } + /** + *INTERNAL USE ONLY: for use with scripting API bridges + */ public String onChangeJ(int minSize, Object observer) { if (minSize == 0) { return onChangeDo(Settings.ObserveMinChangedPixels, observer); @@ -2521,14 +2570,31 @@ public class Region { return name; } + /** + * start an observer in this region that runs forever (use stopObserver() in handler) + * for details about the observe event handler: {@link SikuliEventObserver} + * for details about APPEAR/VANISH/CHANGE events: {@link SikuliEvent} + * @param secs + * @return + */ public void observe() { observe(Float.POSITIVE_INFINITY); } + /** + * start an observer in this region for the given time + * for details about the observe event handler: {@link SikuliEventObserver} + * for details about APPEAR/VANISH/CHANGE events: {@link SikuliEvent} + * @param secs + * @return + */ public boolean observe(double secs) { return observeDo(secs); } + /** + *INTERNAL USE ONLY: for use with scripting API bridges + */ public void observeJ(double secs, boolean bg) { if (bg) { observeInBackground(secs); @@ -2537,7 +2603,7 @@ public class Region { } } - public boolean observeDo(double secs) { + private boolean observeDo(double secs) { if (evtMgr == null) { Debug.error("Region: observe: Nothing to observe (Region might be invalid): " + this.toStringShort()); return false; @@ -2583,6 +2649,13 @@ public class Region { return Observer.hasEvents(this); } + /** + * start an observer in this region for the given time that runs in background + * for details about the observe event handler: {@link SikuliEventObserver} + * for details about APPEAR/VANISH/CHANGE events: {@link SikuliEvent} + * @param secs + * @return + */ public void observeInBackground(double secs) { if (observing) { Debug.error("Region: observeInBackground: already running for this region. Only one allowed!"); @@ -2608,6 +2681,9 @@ public class Region { } } + /** + * stops a running observer + */ public void stopObserver() { Debug.log(2, "Region: observe: request to stop observer for " + this.toStringShort()); observing = false; @@ -3059,6 +3135,17 @@ public class Region { getRobotForRegion().keyUp(keys); } + /** + * Compact alternative for type() with more options <br /> + * - special keys and options are coded as #X-XN. or #X+ or #X- <br /> + * where X-X and X are refrences for special keys and N is an otional repeat factor <br /> + * the trailing . ends the special key, a + or - does the same, <br /> + * but signals press-and-hold or release additionally.<br /> + * a #Wn. inserts a wait of n millisecs or n secs if n < 60 <br /> + * for more details and examples consult the docs <br /> + * @param text a coded text interpreted as a series of key actions (press/hold/release) + * @return + */ public int write(String text) { Debug.info("Write: " + text); char c; diff --git a/API/src/main/java/org/sikuli/script/SikuliEvent.java b/API/src/main/java/org/sikuli/script/SikuliEvent.java index 963c720..bd18316 100755 --- a/API/src/main/java/org/sikuli/script/SikuliEvent.java +++ b/API/src/main/java/org/sikuli/script/SikuliEvent.java @@ -14,33 +14,68 @@ public class SikuliEvent { APPEAR, VANISH, CHANGE, GENERIC } + /** + * the event's type as SikuliEvent.APPEAR, .VANISH, .CHANGE + */ public Type type; - public Region region = null; - // AppearEvent must have a match - // VanishEvent may have a match, depending on if the pattern appeared before - public Match match = null; - // ChangeEvent has 0+ changes. - public List<Match> changes = null; - // the pattern for observing this event - public Object pattern = null; + + private Region region = null; + private Match match = null; + private List<Match> changes = null; + private Object pattern = null; public SikuliEvent() { } + /** + * INTERNAL USE ONLY: creates an observed event + */ public SikuliEvent(Object ptn, Match m, Region r) { region = r; match = m; pattern = ptn; } + /** + * + * @return this event's observer's region + */ public Region getRegion() { return region; } + + protected void setRegion(Region r) { + region = r; + } + /** + * + * @return the observed match (APEAR, VANISH) + */ public Match getMatch() { return match; } + protected void setMatch(Match m) { + match = m; + } + + /** + * + * @return a list of observed changes as matches (CHANGE) + */ + public List<Match> getChanges() { + return changes; + } + + protected void setChanges(List<Match> c) { + changes = c; + } + + /** + * + * @return the used pattern for this event's observing + */ public Pattern getPattern() { if (pattern.getClass().isInstance("")) { return (new Pattern((String) pattern)); @@ -49,14 +84,27 @@ public class SikuliEvent { } } + /** + * tell the observer to repeat this event's observe action immediately + * after returning from this handler (APPEAR, VANISH) + */ public void repeat() { repeat(0); } + /** + * tell the observer to repeat this event's observe action after given time in secs + * after returning from this handler (APPEAR, VANISH) + * @param secs + */ public void repeat(long secs) { region.getEvtMgr().repeat(type, pattern, match, secs); } + /** + * only for (APPEAR, VANISH) + * @return the number how often this event has already been triggered until now + */ public int getCount() { if (type == Type.CHANGE) { return 0; @@ -65,6 +113,9 @@ public class SikuliEvent { } } + /** + * stops the observer after returning from the handler + */ public void stopObserver() { region.stopObserver(); } diff --git a/API/src/main/java/org/sikuli/script/SikuliEventChange.java b/API/src/main/java/org/sikuli/script/SikuliEventChange.java index b37bf32..daecc2f 100755 --- a/API/src/main/java/org/sikuli/script/SikuliEventChange.java +++ b/API/src/main/java/org/sikuli/script/SikuliEventChange.java @@ -11,13 +11,13 @@ import java.util.List; public class SikuliEventChange extends SikuliEvent { public SikuliEventChange(List<Match> results, Region r){ type = Type.CHANGE; - changes = results; - region = r; + setChanges(results); + setRegion(r); } @Override public String toString(){ return String.format("ChangeEvent on %s | %d changes", - region, changes.size()); + getRegion(), getChanges().size()); } } diff --git a/IDE/src/main/java/org/sikuli/ide/EditorViewFactory.java b/IDE/src/main/java/org/sikuli/ide/EditorViewFactory.java index 4dd3c90..467d884 100755 --- a/IDE/src/main/java/org/sikuli/ide/EditorViewFactory.java +++ b/IDE/src/main/java/org/sikuli/ide/EditorViewFactory.java @@ -156,42 +156,54 @@ class SyntaxHighlightLabelView extends LabelView { "__FILE__", "__LINE__", "require" }; private static String[] keywordsSikuliClass = { - "Region", "Screen", "Match", "Pattern", - "Location", "Env", "Key", "Button", "Finder", - "App", "KeyModifier", "Mouse", "Image", "ImagePath", "ImageGroup", - "ImageFind", "ImageFinder" + "Screen", "Region", "Location", "Match", "Pattern", + "Env", "Key", "Button", "Finder", + "App", "KeyModifier", "Mouse", "Keys", "Image", "ImagePath", "ImageGroup", + "ImageFind", "ImageFinder", "Settings", }; private static String[] keywordsSikuli = { - "find", "wait", "findAll", "waitVanish", "exists", - "click", "doubleClick", "rightClick", "hover", "wheel", - "type", "paste", + "find", "wait", "findAll", "findText", "findAllText", "waitVanish", "exists", "text", + "click", "doubleClick", "rightClick", "hover", "wheel", "delayClick", + "type", "paste", "write", "delayType", "dragDrop", "drag", "dropAt", "mouseMove", "mouseDown", "mouseUp", "keyDown", "keyUp", - "onAppear", "onVanish", "onChange", "observe", "stopObserver", - "popup", "capture", "input", "sleep", "run", - "switchApp", "openApp", "closeApp", + "onAppear", "onVanish", "onChange", "observe", "stopObserver", "isObserving", + "popup", "input", "sleep", "run", + "switchApp", "openApp", "closeApp", "use", "useRemote", "ucode", "load", "assertExist", "assertNotExist", - "selectRegion", - "getOS", "getMouseLocation", "exit", + "capture", "selectRegion", + "getOS", "getMouseLocation", "exit", //Region - "right", "left", "above", "below", "nearby", "inside", - "getScreen", "getCenter", + "right", "rightAt", "left", "leftAt", "above", "aboveAt", "below", "belowAt", + "nearby", "inside", "grow", "union", "intersection", + "getScreen", "getCenter", "setCenter", "setSize", "setLocation", "setX", "setY", "setW", "setH", "setRect", "setROI", "getX", "getY", "getW", "getH", "getRect", "getROI", - "highlight", + "highlight", "add", "getLastScreenImageFile", "getNumberScreens", "getBounds", + "contains", "containsMouse", "atMouse", + "getTopLeft", "setTopLeft", "getTopRight", "setTopRight", + "getBottomLeft", "setBottomLeft", "getBottomRight", "setBottomRight", + "get", "setRows", "getRows", "setCols", "setCols", "getRowH", "getColW", + "setRaster", "getRow", "getCol", "getCell", + "getImage", //Pattern "similar", "targetOffset", "getLastMatch", "getLastMatches", "getTargetOffset", "getFilename", //global - "setAutoWaitTimeout", "setBundlePath", "setShowActions", - "setThrowException", + "setAutoWaitTimeout", "setBundlePath", "setShowActions", "setThrowException", + "getAutoWaitTimeout", "getBundlePath", "getShowActions", "getThrowException", + "setFindFailedResponse", "getFindFailedResponse", + "setWaitScanRate", "getWaitScanRate", + "setObserveScanRate", "getObserveScanRate", + "setWaitForVanish", "getWaitForVanish", + "showScreens", "resetScreens", "showMonitors", "resetMonitors", "hasNext", "next", "destroy", "exact", "offset", "getOSVersion", "getScore", "getTarget", - "getBundlePath", "getAutoWaitTimeout", "getThrowException", "getClipboard", - "addImagePath", "removeImagePath", "getImagePath", + "addImagePath", "removeImagePath", "getImagePath", "addImportPath", "resetImagePath", + "getParentPath", "makePath", //App class "open", "close", "focus", "window", "focusedWindow",}; private static String[] constantsSikuli = { -- Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/pkg-java/sikuli.git _______________________________________________ pkg-java-commits mailing list [email protected] http://lists.alioth.debian.org/cgi-bin/mailman/listinfo/pkg-java-commits
