JKeyMaster 技术文档

2024-12-23 14:49:08作者：仰钰奇

1. 安装指南

环境准备

在开始安装前，确保您的系统中已安装以下软件：

Java 1.6 或更高版本
Maven

获取源码

从 GitHub 上克隆 JKeyMaster 项目：

git clone git@github.com:tulskiy/jkeymaster.git

构建项目

在项目根目录下执行以下命令构建项目：

mvn clean install

对于 jkeymaster-dbus，需要先构建一些依赖：

git clone git@github.com:tulskiy/libmatthew-java.git
cd libmatthew-java
mvn clean install

git clone git@github.com:tulskiy/dbus-java.git
cd dbus-java
mvn clean install -DskipTests

然后在项目根目录下，使用 linux 配置文件构建：

mvn -P linux clean install

2. 项目的使用说明

JKeyMaster 是一个 Java 库，提供统一的接口注册全局热键，支持以下平台：

Windows
基于X11的系统（理论上适用于所有Linux发行版和PCBSD，但仅在某些Linux发行版和PCBSD上测试过）
Mac OSX

3. 项目API使用文档

JKeyMaster 的主要类是 Provider。要获取当前平台的热键提供者，可以使用以下代码：

Provider provider = Provider.getCurrentProvider(useSwingEventQueue);

其中 useSwingEventQueue 是一个布尔参数，用于指定是否在 Swing 事件队列上触发事件，这对于您的热键监听器将直接访问或修改 Swing 组件时非常有用。

Provider 类提供了两种注册热键的方法：

一种接受 AWT KeyStroke：

provider.register(KeyStroke.getKeyStroke("control shift PLUS"), listener);

另一种接受 MediaKey 参数：

provider.register(MediaKey.MEDIA_NEXT_TRACK, listener);

目前无法取消注册特定的热键，但可以重置所有热键。

使用完库后，需要重置热键并停止提供者：

provider.reset();
provider.stop();

对于某些系统，DBus 不允许注册媒体键的热键。此时可以使用 GnomeMediaProvider 类。只需创建一个新实例并使用它与媒体键注册热键即可。它实现了与其他提供者相同的 API：

final GnomeMediaProvider provider = new GnomeMediaProvider("test");
provider.register(MediaKey.MEDIA_STOP, new HotKeyListener() {...});

但是，这需要额外的本地库。您需要让用户安装以下软件：

# apt-get install libunixsocket-java

如果遇到 UnsatisfiedLinkError，需要找到 libunixsocket-java.so 文件的位置并添加到 -Djava.library.path=$YOUR_PATH。它通常是 /usr/lib/jni 或 /usr/local/lib/jni。

4. 项目安装方式

如果您想通过 Maven 引入 JKeyMaster，可以在您的项目的 pom.xml 文件中添加以下依赖：

发布版本

<dependencies>
    <dependency>
        <groupId>com.github.tulskiy</groupId>
        <artifactId>jkeymaster</artifactId>
        <version>1.3</version>
    </dependency>
</dependencies>

快照版本

<dependencies>
    <dependency>
        <groupId>com.github.tulskiy</groupId>
        <artifactId>jkeymaster</artifactId>
        <version>1.4-SNAPSHOT</version>
    </dependency>
</dependencies>

<repositories>
    <repository>
        <id>snapshots-repo</id>
        <url>https://oss.sonatype.org/content/repositories/snapshots</url>
    </repository>
</repositories>