Usage in Java programming

valid for 1.1.0

(differences in 1.0.1 see at the end)

... and with Jython, JRuby as well

(or any other Java aware scripting language)

Using SikuliX with IDE's like Netbeans, Eclipse

programming with Java or Java based scripting (Jython, JRuby, Scala, Groovy, Clojure, ...)

• take care, that sikulixapi.jar is in the Java classpath of your project
• you should ALWAYS leave the Sikuli stuff in its installation folder,
  means: do not have copies somewhere else on the same system.
  This avoids odd errors when updating to new versions.
  In IDE's and other situations always use references/links to the original Sikuli stuff.
• the native stuff is exported at runtime to the folder containing sikulixapi.jar
  TAKE CARE on WINDOWS:
  Sikuli tries to add the libs path to the registry at runtime.
  To avoid library clashes, purge everything from system environment, that has to do with previously used Sikuli versions.
  SikuliX does not need any path entries to the used Java version in the system environment. So purge these too, if not needed for other stuff than SikuliX.

Used Images:
Sikuli searches for image files in the standard in the current working directory (Java property "user.dir") So e.g. in Netbeans you can store images in your project folder and they will be found when simply using "some-image.png". Relative pathnames are possible too (e.g. "images/some-image.png").

Find a Java usage example here ...
... and tons of more samples in the net - Google is your friend;-)

… but this is a simple test program as well:

import org.sikuli.script.*;
import org.sikuli.basics.Debug;
class Test {
  public static void main(String[] args) throws FindFailed {
    Debug.setDebugLevel(3);
    Screen s = new Screen();
    s.find(s.userCapture().getFile()).highlight(2)
  }
}

• it gives some more debug output
• it should ask you to capture something
• … that in turn is searched on the screen
• … and highlighted if found

Special information on using Jython in IDEs like Eclipse or running your own Jython

When using Jython e.g. in Eclipse or standalone, the following setup is the easiest and most effective:

• mind the above information about usage with Java

• have a reference to sikulixapi.jar in your project's Java class path
  (your IDE's project's external libraries setup or simply in Java class path with other setups)
  (do not use sikulix.jar in this case, since the contained Jython might collide with the Jython you want to use)

in your main script at the beginning add:
import org.sikuli.basics.SikulixForJython
from sikuli import *

(do not use from sikuli.Sikuli import * any longer)

The first entry is new and automagically adds the path of the Sikuli Jython API to the Python sys.path at runtime (no need to add it yourself, but you might ;-).

It adds another convenience: To support Jython code completion in the editor of IDE's, you usually need a reference to the Jython sources of Sikuli in your project setup. To no longer have the need to extract the stuff from the jar yourself, Sikuli will automagically export the folder Lib/sikuli at runtime.
To support code completion just add to your setup:
...xxx.../Lib
where ...xxx... is the path to the folder containing sikuli-java.jar

As in the past from sikuli import * is also needed in every module, that is imported and uses Sikuli features.

what is different in version 1.0.1

• the jar to use: sikuli-java.jar
• the Lib folder is: ...xxx.../libs/Lib (only available after a first run)