# Class LinuxFFMKeys

java.lang.Object
org.stianloader.jxkbwayland.LinuxFFMKeys

All Implemented Interfaces:
  `Closeable, AutoCloseable`

public class LinuxFFMKeys extends Object implements Closeable
`LinuxFFMKeys` is a class wrapping the XKB and (indirectly) the wayland-client libraries to provide low level information about the keyboard.

As its name suggests, this class achieves the wrapping process using Java's FFM library (also known as Project Panama).

VERY IMPORTANT: The `LinuxFFMKeys` instance will only be usable two frames (or more specifically, two `GLFW.glfwPollEvents()` calls) after invocation. This is due to limitations with the wayland registration process as it is dependent on wayland listeners to obtain the keyboard handle and the keyboard layout from the GLFW-provided handles.

This class will fail to initialize if both the `libxkbcommon.so.0` and `libxkbcommon.so` binaries are missing from the system library path. Similarly, no instances of this class can be created via `LinuxFFMKeys(LinuxKeyCallback)` if both the `libwayland-client.so.0` and `libwayland-client.so` binaries are missing from the system library path (as far as `SymbolLookup.libraryLookup(String, Arena)`RESTRICTED is concerned).

The constructor of this class will fail if the current GLFW platform is not wayland, i.e. `GLFWNativeWayland.glfwGetWaylandDisplay()` returns `0`.

## Nested Class Summary

Nested Classes
Modifier and Type
Class
Description
`static enum`
`LinuxFFMKeys.Keysym`
A Keysym (Key Symbol) in the context of XKB represents the layout-specific and keystate-specific (i.e.
`static interface`
`LinuxFFMKeys.LinuxKeyCallback`
Linux keyboard callback event listener.

## Field Summary

Fields
Modifier and Type
Field
Description
`static final @NotNull String`
`LOGGER_NAME`
The name of the `Logger` used for logging warning messages related to invalid/unsupported application state/use that is passed to wayland (this usually causes crashes or undesired behaviour, but might sometimes be just fine - we can't really know, hence the log messages).

## Constructor Summary

Constructors
Constructor
Description
`LinuxFFMKeys(@NotNull LinuxFFMKeys.LinuxKeyCallback keyCallback)`
Create a new `LinuxFFMKeys` instance, registering.

## Method Summary

Modifier and Type
Method
Description
`void`
`close()`
Release all XKB and Wayland related resources.
`final @Nullable String`
`getKeyName(int evcode)`
For an enumeration of available keycodes, see the Linux input-event-codes.h file
`final @Nullable String`
`getKeyName(int evcode, @NotNull Arena arena)`
For an enumeration of available keycodes, see the Linux input-event-codes.h file
`@Nullable String`
`getKeyName(int evcode, @NotNull Arena arena, @NotNull LinuxFFMKeys.Keysym nameMethod)`
For an enumeration of available keycodes, see the Linux input-event-codes.h file
`final @Nullable String`
`getKeyName(int evcode, @NotNull LinuxFFMKeys.Keysym nameMethod)`
For an enumeration of available keycodes, see the Linux input-event-codes.h file
`@Nullable WaylandTextInput`
`getTextInput()`
Obtains the current wrapper around the used wayland text input protocol, may return `null` if the wayland context is not initialized yet, or if the wayland compositor doesn't support zwp_text_input_v3 or another text input protocol that jXKBWayland supports.

### Methods inherited from class Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

## Field Details

### LOGGER_NAME

@NotNull public static final @NotNull String LOGGER_NAME
The name of the `Logger` used for logging warning messages related to invalid/unsupported application state/use that is passed to wayland (this usually causes crashes or undesired behaviour, but might sometimes be just fine - we can't really know, hence the log messages).

See Also:
  - Constant Field Values

## Constructor Details

### LinuxFFMKeys

public LinuxFFMKeys(@NotNull @NotNull LinuxFFMKeys.LinuxKeyCallback keyCallback)
Create a new `LinuxFFMKeys` instance, registering.

VERY IMPORTANT: The `LinuxFFMKeys` instance will only be usable two frames (or more specifically, two `GLFW.glfwPollEvents()` calls) after invocation. This is due to limitations with the wayland registration process as it is dependent on wayland listeners to obtain the keyboard handle and the keyboard layout from the GLFW-provided handles.

Parameters:
  `keyCallback` - The callback used which informs the user of keyboard events.

## Method Details

### close

public void close() throws IOException
Release all XKB and Wayland related resources. And make this instance unusable for any further calls. Repeated invocations to this methods will result in the method behaving as a NOP.

Note: You probably don't want to ever call this method, the side effects of this method are somewhat undefined, as e.g. wayland listeners may or may not get unregistered.

Specified by:
  `close` in interface `AutoCloseable`
Specified by:
  `close` in interface `Closeable`
Throws:
  `IOException` - If a resource cannot be freed for whatever reason.

### getKeyName

@Nullable public final @Nullable String getKeyName(int evcode)
For an enumeration of available keycodes, see the Linux input-event-codes.h file

Note that the evdev keycode is offset from the X11/XKB keycode by 8. In other words, `KEY_ESC` is `1` for evdev keycodes (the kind of keycode inserted into this library), whilst `KEY_ESC` is `9` as far as XKB is concerned (`getKeyName(int)` automatically converts evdev keycodes to XKB-compatible keycodes).

Parameters:
  `evcode` - The evdev keycode for the key to use.
Returns:
  The name of the key defined by the evcode corresponding to the current keyboard state and the `LinuxFFMKeys.Keysym.NAME` method, or `null` if the `LinuxFFMKeys` instance is not yet ready (it takes two frames to initialize `LinuxFFMKeys` due to wayland callbacks).

### getKeyName

@Nullable public final @Nullable String getKeyName(int evcode, @NotNull @NotNull Arena arena)
For an enumeration of available keycodes, see the Linux input-event-codes.h file

Note that the evdev keycode is offset from the X11/XKB keycode by 8. In other words, `KEY_ESC` is `1` for evdev keycodes (the kind of keycode inserted into this library), whilst `KEY_ESC` is `9` as far as XKB is concerned (`getKeyName(int, Arena)` automatically converts evdev keycodes to XKB-compatible keycodes).

Parameters:
  `evcode` - The evdev keycode for the key to use.
  `arena` - The `Arena` to use for short-lived thread-local allocations. Allocated memory segments are not referenced after this method exits.
Returns:
  The name of the key defined by the evcode corresponding to the current keyboard state and the `LinuxFFMKeys.Keysym.NAME` method, or `null` if the `LinuxFFMKeys` instance is not yet ready (it takes two frames to initialize `LinuxFFMKeys` due to wayland callbacks).

### getKeyName

@Nullable public @Nullable String getKeyName(int evcode, @NotNull @NotNull Arena arena, @NotNull @NotNull LinuxFFMKeys.Keysym nameMethod)
For an enumeration of available keycodes, see the Linux input-event-codes.h file

Note that the evdev keycode is offset from the X11/XKB keycode by 8. In other words, `KEY_ESC` is `1` for evdev keycodes (the kind of keycode inserted into this library), whilst `KEY_ESC` is `9` as far as XKB is concerned (`getKeyName(int, Arena, Keysym)` automatically converts evdev keycodes to XKB-compatible keycodes).

Parameters:
  `evcode` - The evdev keycode for the key to use.
  `arena` - The `Arena` to use for short-lived thread-local allocations. Allocated memory segments are not referenced after this method exits.
  `nameMethod` - The method by which the key's name should be obtained from the KXB Keysym (Key Symbol) instance.
Returns:
  The name of the key defined by the evcode corresponding to the current keyboard state and chosen `LinuxFFMKeys.Keysym` method, or `null` if the `LinuxFFMKeys` instance is not yet ready (it takes two frames to initialize `LinuxFFMKeys` due to wayland callbacks).

### getKeyName

@Nullable public final @Nullable String getKeyName(int evcode, @NotNull @NotNull LinuxFFMKeys.Keysym nameMethod)
For an enumeration of available keycodes, see the Linux input-event-codes.h file

Note that the evdev keycode is offset from the X11/XKB keycode by 8. In other words, `KEY_ESC` is `1` for evdev keycodes (the kind of keycode inserted into this library), whilst `KEY_ESC` is `9` as far as XKB is concerned (`getKeyName(int, Keysym)` automatically converts evdev keycodes to XKB-compatible keycodes).

Parameters:
  `evcode` - The evdev keycode for the key to use.
  `nameMethod` - The method by which the key's name should be obtained from the KXB Keysym (Key Symbol) instance.
Returns:
  The name of the key defined by the evcode corresponding to the current keyboard state and chosen `LinuxFFMKeys.Keysym` method, or `null` if the `LinuxFFMKeys` instance is not yet ready (it takes two frames to initialize `LinuxFFMKeys` due to wayland callbacks).

### getTextInput

@Nullable public @Nullable WaylandTextInput getTextInput()
Obtains the current wrapper around the used wayland text input protocol, may return `null` if the wayland context is not initialized yet, or if the wayland compositor doesn't support zwp_text_input_v3 or another text input protocol that jXKBWayland supports.

Beware: Wayland's text input protocols run complementary to XKB keybinds. That is, you need to not only rely on wayland text input, but also on `LinuxFFMKeys.Keysym.CHARACTER`. This is because some IME implementations (such as ibus-wayland older versions of plasma-keyboard) might suppress key fire events (e.g. `LinuxFFMKeys.LinuxKeyCallback.onPress(int)`) when text input is enabled using `WaylandTextInput.enableTextInput(int, int, int, int, org.stianloader.jxkbwayland.WaylandTextInput.InputChangeCause)`, however, this removes the ability to use keybinds by extension (if key capture is handled that way). To remove this flaw, certain IMEs such as newer versions of plasma-keyboard don't send events for ordinary keys, only sending the text input events for things such as diacritics.

It is not permissible for a compositor to send key fire events and text input events for the same character at the same time. It's mutually exclusive.

Returns:
  The current wrapper around the text input protocol