Usage in Java programming

... and with Jython as well (or any other Java aware scripting language)

Using Sikuli features when using IDE's like Netbeans, Eclipse
(since 1.0.1)

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

• take care, that one of the Sikuli jars (preferably: sikuli-java.jar, but sikuli-ide.jar or sikuli-script.jar work as well) 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 to the folder containing the used jar at runtime
  TAKE CARE on WINDOWS:
  Sikuli tries to add the libs path to the registry the first time it is used after setup.
  If you already have something of value in the user path entry in system settings, then you should do the following before the first usage of Sikuli after setup: (reason: the existing content is overridden - a bug)
  
• supposing you have put the Sikuli stuff into the folder C:\SikuliX
• then add C:\SikuliX\libs to the user path entry manually
• this really is only necessary if in
  system prefs -> system … -> system -> extended settings -> environment …
  in the upper part an entry PATH already exists, that contains something of value
• in the case Sikuli adds the libs path to the registry, you get a rather fancy error message: Just do what is said: log out from the current Windows session and login again, to make that entry useable or even restart Windows completely (this is also necessary, if you add it manually)
• purge everything from system environment, that has to do with previously used Sikuli versions.

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;-)

Special information on using Jython in IDEs like Eclipse or running your own Jython
(since 1.0.1)

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

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

• have a reference to sikuli-java.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 sikuli-ide.jar nor sikuli-script.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 to the libs folder (containing the native stuff) at runtime.
To support code completion just add to your setup:
...xxx.../libs/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.