Kristian Kraljić You may compare programming with poetry,
a harmonic script is a piece of creativity which will last forever.
- Kristian Kraljić

Java – Global (low level) Keyboard / Mouse Hook

by Kristian Kraljic, February 9, 2016

About five years ago I started this blog by picking up an idea of Johannes Schüth (Jotschi) about a global keyboard and mouse listener for Java. Today I am very happy to announce the next major version of the library now available on GitHub!

system-hook-logo

Keyboard and mouse events in Java only work, if the registered component is in focus. For example, in case a window looses its focus (e.g. when minimized), it stops receiving any more events. Through a low-level system-wide hook it’s possible to deliver those events regardless. You’ll find all sources of the latest release, as well as binary bundles / prepackaged Java archives (JAR) on the GitHub project page.

The old post describes all changes I did to the initial version by Johannes (Jotschi). For the new major release I again reworked nearly every part of the library, to make it more stable and versatile. Here is what I did:

  • Optimized the native library C code, fixed bugs and removed all parts requireing a C++ compiler in the first place.
  • Renamed the event classes and listener interfaces and prepended Global to avoid conflicts with existing (Swing) event listeners.
  • Added support for mouseWheel events to the GlobalMouseListener.
  • Again allowed negative "out of bounds" values for GlobalMouseEvents, to also track the mouse pointer off screen (e.g. on multi-monitor setups).
  • Improved the threading concept and implemented a native error handling. The GlobalKeyboardHook and GlobalMouseHook constructors will now throw a UnsatisfiedLinkError if the native libraries can not be loaded or a RuntimeException in case hooking fails.
  • All the code has been moved to GitHub and binaries are now beeing continuously built by AppVeyor. Feel free to contribute on GitHub!

(Again) Last but not least, please share your ideas and problems in the comments. I will try to enhance the Global Keyboard / Mouse Hook based on your feedback. For the next release let’s see if we can get Linux and / or Mac OSX support going.

150 Comments

  1. Daniel says:

    I tried to create a basic GlobalKeyboardHook and kept getting this error and I don’t know how to fix it. could you help me?

    NATIVE: DllMain – DLL_PROCESS_ATTACH
    NATIVE: registerHook – Hook start
    NATIVE: registerHook – Hook failed with error 126: The specified module could not be found.

    Exception in thread “main” java.lang.RuntimeException: Low-level keyboard hook failed (-2)
    at lc.kra.system.keyboard.GlobalKeyboardHook$NativeKeyboardHook.(GlobalKeyboardHook.java:169)
    at lc.kra.system.keyboard.GlobalKeyboardHook$2.(GlobalKeyboardHook.java:89)
    at lc.kra.system.keyboard.GlobalKeyboardHook.(GlobalKeyboardHook.java:89)
    at MainClass.main(MainClass.java:7)

    • Hello Daniel, which operating system / JVM architecture are you wofking on? You get the debug output, so you downloaded one of the architecture specific packages from AppVeyor. Make sure you use the 32-bit DLLs / JAR, with a 32-bit JVM on a Windows 32-bit machine only. Use the 64-bit files, with a 64-bit JVM on a 64-bit operating system. Any other combination of those could cause the error you posted.

      Hope this helps. Regards, Kristian

    • Daniel says:

      I am running windows 10 64-bit with JVM JDK 1.8 and I made sure I downloaded the JAR file located in the Configuration: Debug; Platform: x64/ artifacts/target/system-hook-2.1.jar. I am referencing the file inside eclipse’s project folder. the same thing happened when I tried to export it and run it as an executable JAR file.

    • Hey Daniel. Hope we can figure this out. Just to be sure. Especially if you have multiple JVMs installed, it often happens that you execute on a 32-bit JVM, even if you are running it on a 64-bit operating system. Could you please check and run the following command on your console:

      java -version

      The last line should say something similar to:

      Java HotSpot(TM) 64-Bit Server VM (build 25.66-b18, mixed mode)

    • Daniel says:

      java version “1.8.0_71”
      Java(TM) SE Runtime Environment (build 1.8.0_71-b15)
      Java HotSpot(TM) 64-Bit Server VM (build 25.71-b15, mixed mode)

    • Daniel says:

      for some reason, restarting my computer solved the problem.

    • Hello Daniel, glad that helped. Sorry that I had no time to figure out the problem. Please do also see the answer I have given to Mohammad on the 3rd of March 2016, always shut down your hook properly, otherwise you run out of handles quickly.

  2. John says:

    Hi. Thank you for your interested library.
    But I’m having a problem using it.
    How can I solve the Low-level keyboard hook failed?

    • Hello John, well this heavily depends on why the hooking fails. If it works for a certain amount of times and then fails, I suggest to check the answer I have given to Mohammad on the 3rd of March 2016, always shut down your hook properly, otherwise you run out of handles quickly. If this doesn’t help, please download the debug DLLs as described here, to get a extended log output.

  3. Subin says:

    Hey Kristian,
    I am getting this excepion:

    Exception in thread “Global Keyboard Hook Thread” java.lang.UnsatisfiedLinkError: lc.kra.system.keyboard.GlobalKeyboardHook$NativeKeyboardHook.registerHook()I
    Global keyboard hook successfully started, press [escape] key to shutdown.
    at lc.kra.system.keyboard.GlobalKeyboardHook$NativeKeyboardHook.registerHook(Native Method)
    at lc.kra.system.keyboard.GlobalKeyboardHook$NativeKeyboardHook.run(GlobalKeyboardHook.java:174)

  4. Ciao,lo voglio proprio provare, si può sostituire la farina di segale con altra farina? Ne ho un sacchetto di avena, potrebbe andare?Grazie per la continua fonte di ispirazione.

  5. DziÅ› to dziwne miast Kraków nawiedziÅ‚ towarzysz Leszek rozmawiano z nim. Dziennikarzowi wychodziÅ‚o, że twarzom wszelakiej krakowskiej lewicy jest antyklerykalny towarzysz prof, brat Yeti jak to ujÄ…Å‚eÅ›.WidzÄ™ odrobinÄ™ podobieÅ„stwa i raczej różnice. Yeti – suchary i zupka, tow.prof. – chrzan. Yeti jest pomocny a tow.prof. jedzie z “mowÄ… nienawiÅ›ci”.