Register global keystrokes using JNA

Hello, in this article I will tell you how to register global keystrokes from Java under Windows, Linux, BSD and Mac OSX using the excellent JNA library.

What is JNA for?

Java is difficult with the desktop; for some things you need to write bridges to interact with the operating system. One of these functionalities is global hotkeys, which are very popular in audio players, when even in the hidden state the program can be controlled using certain keyboard shortcuts or media buttons. JNA comes to the rescue - add-on jni and libffi to call native libraries, it supports almost all popular platforms, has been developed for a long time and is very stable.

For Java, there are already some fairly stable libraries for all platforms: JIntelliType for Windows, which even supports media buttons, JXGrabKey for Linux systems, and ossuport-connector for Mac OSX. However, they all use jni, have a different interface, and it is not always convenient to work with libraries on jni, because you need to prescribe paths to native libraries, deal with system capacity, etc. Plus, this will be an interesting exercise in using JNA, because this task You can make it completely on java with a fairly small effort and get easily supported cross-platform code.

Windows

The easiest way to work with global hotkeys in Windows:
')

public class User32 {
static {
Native . register ( NativeLibrary. getInstance ( "user32" , W32APIOptions. DEFAULT_OPTIONS ) ) ;
}

public static final int MOD_ALT = 0x0001 ;
public static final int MOD_CONTROL = 0x0002 ;
public static final int MOD_SHIFT = 0x0004 ;
public static final int MOD_WIN = 0x0008 ;
public static final int WM_HOTKEY = 0x0312 ;

public static native boolean RegisterHotKey ( Pointer hWnd, int id, int fsModifiers, int vk ) ;
public static native boolean UnregisterHotKey ( Pointer hWnd, int id ) ;
public static native boolean PeekMessage ( MSG lpMsg, Pointer hWnd, int wMsgFilterMin, int wMsgFilterMax, int wRemoveMsg ) ;

public static class MSG extends Structure {
public Pointer hWnd ;
public int message ;
public int wParam ;
public int lParam ;
public int time ;
public int x ;
public int y ;
}
}

Here we use the so-called direct mapping . Besides the fact that it is faster, it is easier to work with it, since you can make static import and use the methods as native ones. We need three methods from User32:

• RegisterHotKey - actually registers hotkey. The first parameter can be set to null, since we have no window. The second parameter is the unique number of our hotkey, generated by us, it will later be used to identify the hotkey and to delete it via UnregisterHotKey . In fsModifiers, we write what modifiers we need (ctrl, shift, alt or win). In vk we write virtual code. Interestingly, the virtual codes used in KeyEvent in AWT almost always coincide with virtual codes in Windows:
  
  

  // register the combination WIN + F
  RegisterHotKey ( null , 1 , 0x8, KeyEvent . VK_F ) ;

  
  
• PeekMessage - checks incoming messages and clogs them into the MSG structure. This uses the non-blocking PeekMessage call instead of the blocking GetMessage due to the fact that all methods must be called from one thread and we need to be able to control this thread:
  

  MSG msg = new MSG ( ) ;
  while ( listen ) {
  while ( PeekMessage ( msg, null , 0 , 0 , PM_REMOVE ) ) {
  if ( msg. message == WM_HOTKEY ) {
  System . out . println ( "Yattaaaa. Hotkey with id" + msg. wParam ) ;
  }
  }
  
  Thread . sleep ( 300 ) ;
  }

  
  Here we register a combination of WIN + F and check messages every 300 ms.

X11

Unfortunately, it will not be possible to use direct mapping for X11, as this for some reason causes errors when working with FreeBSD. Mapping looks a bit more complicated:

public interface X11 extends Library {
public static X11 Lib = ( X11 ) Native . loadLibrary ( "X11" , X11. class ) ;
public static final int GrabModeAsync = 1 ;
public static final int KeyPress = 2 ;

public static final int ShiftMask = ( 1 ) ;
public static final int LockMask = ( 1 << 1 ) ;
public static final int ControlMask = ( 1 << 2 ) ;
public static final int Mod1Mask = ( 1 << 3 ) ;
public static final int Mod2Mask = ( 1 << 4 ) ;
public static final int Mod3Mask = ( 1 << 5 ) ;
public static final int Mod4Mask = ( 1 << 6 ) ;
public static final int Mod5Mask = ( 1 << 7 ) ;

public Pointer XOpenDisplay ( String name ) ;
public NativeLong XDefaultRootWindow ( Pointer display ) ;
public byte XKeysymToKeycode ( Pointer display, long keysym ) ;
public int XGrabKey ( Pointer display, int code, int modifiers, NativeLong root, int ownerEvents, int pointerMode, int keyBoardMode ) ;
public int XUngrabKey ( Pointer display, int code, int modifiers, NativeLong root ) ;
public int XNextEvent ( Pointer display, XEvent event ) ;
public int XPending ( Pointer display ) ;
public int XCloseDisplay ( Pointer display ) ;

public static class XEvent extends Union {
public int type ;
public XKeyEvent xkey ;
public NativeLong [ ] pad = new NativeLong [ 24 ] ;
}

public static class XKeyEvent extends Structure {
public int type ; // of event
public NativeLong serial ; // # of last request processed by server
public int send_event ; // true if this came from a SendEvent request
public Pointer display ; // public display the event was read from
public NativeLong window ; // "event" window it is reported relative to
public NativeLong root ; // root window that the event occurred on
public NativeLong subwindow ; // child window
public NativeLong time ; // milliseconds
public int x, y ; // pointer x, y coordinates in event window
public int x_root, y_root ; // coordinates relative to root
public int state ; // key or button mask
public int keycode ; // detail
public int same_screen ; // same screen flag
}
}

• XOpenDisplay, XCloseDisplay, XDefaultRootWindow - receive and close the default display and root window.
• XKeysymToKeycode - converts a character (character descriptions are taken in keysymdef.h ) into a key code, you will need it later:
  

  // for letters and numbers, the symbol number also corresponds to the value in KeyEvent
  byte code = XKeysymToKeycode ( display, KeyEvent . VK_F ) ;
  

• XGrabKey, XUngrabKey - register and delete hotkeys. In code, the value obtained earlier with XKeysymToKeycode is written here, modifiers are written into modifiers, and the root value is written from XDefaultRootWindow. The remaining values ​​are clogged with units. Interestingly, in X11, the pressed ScrollLock, NumLock, CapsLock, and some other Lock are also considered modifiers, so instead of one hotkey, you have to register 16 for each possible combination:
  

  // this hack is found in the global hotkey plugin in the deadbeef player
  for ( int flags = 0 ; flags < 16 ; i ++ ) {
  int ret = modifiers ;
  if ( ( flags & 1 ) ! = 0 )
  ret | = LockMask ;
  if ( ( flags & 2 ) ! = 0 )
  ret | = Mod2Mask ;
  if ( ( flags & 4 ) ! = 0 )
  ret | = Mod3Mask ;
  if ( ( flags & 8 ) ! = 0 )
  ret | = Mod5Mask ;
  XGrabKey ( display, code, ret, root, 1 , GrabModeAsync, GrabModeAsync ) ;
  // XUngrabKey (display, code, ret, root);
  }
  

  
  Also, unlike Windows, where deleting a hotkey when the program exits is optional, if you do not call XUngrabKey, then X will keep it until restarting.
  
• XPending and XNextEvent - check for availability and extract the following event:
  

  while ( listening ) {
  while ( Lib. XPending ( display ) > 0 ) {
  Lib. XNextEvent ( display, event ) ;
  if ( event. type == KeyPress ) {
  // read our event from union XEvent
  // JNA does not know which field to fill in the union,
  // so he needs to tell which of the fields to count.
  XKeyEvent xkey = ( XKeyEvent ) event. readField ( "xkey" ) ;
  
  // clear garbage modifiers
  int state = xkey. state & ( ShiftMask | ControlMask | Mod1Mask | Mod4Mask ) ;
  System . out . println ( "Yattaaaa, hotkey with code:" + xkey. keycode + "and modifiers:" + state ) ;
  }
  }
  
  Thread . sleep ( 300 ) ;
  }

  
  

Mac osx

The basis of the code for Mac OSX was made up by the workings of Torsten Uhlmann , the author of ossupport-connector:

public interface Carbon extends Library {
public static Carbon Lib = ( Carbon ) Native . loadLibrary ( "Carbon" , Carbon. class ) ;

public static final int cmdKey = 0x0100 ;
public static final int shiftKey = 0x0200 ;
public static final int optionKey = 0x0800 ;
public static final int controlKey = 0x1000 ;

// OS_TYPE concatenates string characters into int
private static final int kEventClassKeyboard = OS_TYPE ( "keyb" ) ;
private static final int typeEventHotKeyID = OS_TYPE ( "hkid" ) ;
private static final int kEventParamDirectObject = OS_TYPE ( "----" ) ;

public Pointer GetEventDispatcherTarget ( ) ;

public int InstallEventHandler ( Pointer inTarget, EventHandlerProcPtr inHandler, int inNumTypes, EventTypeSpec [ ] inList, Pointer inUserData, PointerByReference outRef ) ;
public int RegisterEventHotKey ( int inHotKeyCode, int inHotKeyModifiers, EventHotKeyID. ByValue inHotKeyID, Pointer inTarget, int inOptions, PointerByReference outRef ) ;
public int GetEventParameter ( Pointer inEvent, int inName, int inDesiredType, Pointer outActualType, int inBufferSize, IntBuffer outActualSize, EventHotKeyID outData ) ;
public int RemoveEventHandler ( Pointer inHandlerRef ) ;
public int UnregisterEventHotKey ( Pointer inHotKey ) ;

public class EventTypeSpec extends Structure {
public int eventClass ;
public int eventKind ;
}

public static class EventHotKeyID extends Structure {
public int signature ;
public int id ;

public static class ByValue extends EventHotKeyID implements Structure. ByValue {
}
}

public static interface EventHandlerProcPtr extends Callback {
public int callback ( Pointer inHandlerCallRef, Pointer inEvent, Pointer inUserData ) ;
}
}

• GetEventDispatcherTarget - gets a link to the system event handler
• InstallEventHandler - adds our handler to this event handler. Unlike other platforms, in Carbon, events come asynchronously via callback:
  

  eventHandlerReference = new PointerByReference ( ) ;
  // actually the handler itself
  keyListener = new EventHandler ( ) ;
  
  // JNA magic to create an array from one structure
  EventTypeSpec [ ] eventTypes = ( EventTypeSpec [ ] ) ( new EventTypeSpec ( ) . ToArray ( 1 ) ) ;
  eventTypes [ 0 ] . eventClass = kEventClassKeyboard ;
  eventTypes [ 0 ] . eventKind = kEventHotKeyPressed ;
  
  int status = lib. InstallEventHandler ( Lib. GetEventDispatcherTarget ( ) , keyListener, 1 , eventTypes, null , eventHandlerReference ) ;

  
  Here we specify that we will process keyboard messages, namely pressing hot keys.
  The eventHandlerReference comes back link to the handler that is needed in RemoveEventHandler.
  
  The event handler looks like this:
  

  private class EventHandler implements Carbon. EventHandlerProcPtr {
  public int callback ( Pointer inHandlerCallRef, Pointer inEvent, Pointer inUserData ) {
  EventHotKeyID eventHotKeyID = new EventHotKeyID ( ) ;
  // get event parameters
  int ret = lib. GetEventParameter ( inEvent, kEventParamDirectObject, typeEventHotKeyID, null , eventHotKeyID. Size ( ) , null , eventHotKeyID ) ;
  if ( ret ! = 0 ) {
  logger. warning ( "Could not get event parameters. Error code:" + ret ) ;
  } else {
  // Get and handle event id here
  int eventId = eventHotKeyID. id ;
  logger. info ( "Received event id:" + eventId ) ;
  }
  return 0 ;
  }
  }

  
  
• RegisterEventHotKey - registers a hotkey. At the entrance is the key code. The code table is here . Next, a list of modifiers. Then the EventHotKeyID.ByValue structure, into which our identifier and four-letter signature are clogged. ByValue is used because by default structures are passed by reference, and we need by value. A reference to this hotkey is returned, which is used in the UnregisterEventHotKey:
  
  

  EventHotKeyID. ByValue hotKeyReference = new EventHotKeyID. ByValue ( ) ;
  hotKeyReference. id = 1 ;
  hotKeyReference. signature = OS_TYPE ( "hk01" ) ;
  PointerByReference gMyHotKeyRef = new PointerByReference ( ) ;
  
  int status = lib. RegisterEventHotKey ( code, modifiers, hotKeyReference, Lib. GetEventDispatcherTarget ( ) , 0 , gMyHotKeyRef ) ;

  
  

Conclusion

In general, everything is quite simple, although there were some problems, such as crashes when using direct mapping on FreeBSD, JNA’s failure to get boolean in XGrabKey on an int, strange errors when passing a structure by reference, and not in Carbon, errors generated by X11 if the hotkey is already busy, which just cut down the program, the difficulty of finding any documentation on Carbon.

All this code is compiled into the jkeymaster library under the LGPL 3 license. The interface is based on KeyStroke from Swing; for Windows and X11, you can register media buttons — Play / Pause, Stop, Next Track, Previous Track.

Comments and patches are welcome.

ps The post is written by tulskiy , which, thanks to mgarin, is now in place. So all the benefits to him.