QHotkey

用于桌面Qt应用程序的全局快捷键/热键。

QHotkey是一个可用于创建热键/全局快捷键的类，即在任何地方都能工作的快捷键，与应用程序状态无关。这意味着无论您的应用程序是活跃的、非活跃的、最小化的还是完全不可见的，都能接收到这些快捷键。

特性

适用于Windows、Mac和X11
使用简单，可以使用QKeySequence轻松输入快捷键
支持几乎所有常见按键（取决于操作系统和键盘布局）
允许直接输入按键/修饰符组合
支持同一快捷键的多个QHotkey实例（带有优化）
线程安全 - 可在所有线程中使用（参见线程安全部分）
如需要，允许使用原生键码和修饰符

**注意：**目前不支持Wayland，因为在Wayland上注册全局快捷键simply是不可能的。有关更多详细信息，或在Wayland上实现热键的可能想法，请参见Issue #14。

构建

QHotkey同时支持Qt6和Qt5。使用Qt6时，需要6.2.0或更高版本。可以使用CMake构建系统进行构建。

CMake

CMake的QT_DEFAULT_MAJOR_VERSION变量控制用于构建的Qt主版本，默认为5。例如，使用CMake命令行选项-DQT_DEFAULT_MAJOR_VERSION=6来使用Qt6进行构建。要构建测试应用程序QHotkeyTest，请指定-DQHOTKEY_EXAMPLES=ON。CMake使用示例：

$ cd QHotkey
$ cmake -B build -S . -DQT_DEFAULT_MAJOR_VERSION=6
$ cmake --build build
# cmake --install build

安装

该包作为qpm包提供，de.skycoder42.qhotkey。您可以通过qpmx（首选）或直接通过qpm安装它。

通过qpmx

qpmx是qpm（和其他工具）的前端，具有额外功能，是安装包的首选方式。使用方法：

安装qpmx（参见GitHub - 安装）
安装qpm（参见GitHub - 安装，Windows用户请参见下文）
在项目根目录中，运行qpmx install de.skycoder42.qhotkey

通过qpm

安装qpm（参见GitHub - 安装，Windows用户请参见下文）
在项目根目录中，运行qpm install de.skycoder42.qhotkey
通过在.pro文件中添加include(vendor/vendor.pri)来将qpm包含到您的项目中

查看他们的GitHub - 应用开发者使用指南以了解更多关于qpm的信息。

**Windows用户重要提示：**QPM版本0.10.0（您可以在网站上下载的版本）目前在Windows上存在问题！这个问题已在master分支中修复，但尚未发布。在新版本发布之前，您可以从以下链接下载最新的开发版本：

使用

一般使用方法是为特定热键创建QHotkey实例，注册它们，然后简单地连接到按下热键时发出的信号。

示例

以下示例展示了一个简单的应用程序，它将在后台运行，没有窗口，直到您按下键组合Ctrl+Alt+Q（在Mac上为⌘+⌥+Q）。这将退出应用程序。调试输出将告诉您热键是否成功注册以及它是否被按下。

#include <QHotkey>
#include <QApplication>
#include <QDebug>

int main(int argc, char *argv[])
{
	QApplication app(argc, argv);

	QHotkey hotkey(QKeySequence("Ctrl+Alt+Q"), true, &app); //热键将自动注册
	qDebug() << "是否已注册:" << hotkey.isRegistered();

	QObject::connect(&hotkey, &QHotkey::activated, qApp, [&](){
		qDebug() << "热键已激活 - 应用程序将立即退出";
		qApp->quit();
	});

	return app.exec();
}

**注意：**您需要包含.pri文件才能使其正常工作。

测试

通过运行./HotkeyTest中的示例，您可以测试QHotkey类。有4个部分：

**测试区：**您可以在这里输入一些序列，并尝试不同的按键组合。
**测试项：**一个精选的热键列表。激活它并尝试哪些适合您（*提示：*根据操作系统和键盘布局，很可能有几个不起作用）。
**线程：**勾选复选框可将测试区的2个热键移至单独的线程。这应该不会有任何差异。
原生快捷键：允许您尝试直接使用原生快捷键

日志

默认情况下，如果出现问题（例如，无法转换的按键），QHotkey会打印一些警告消息。QHotkey的所有消息都归类于QLoggingCategory "QHotkey"。如果您想简单地禁用日志记录，请在代码中的某个地方调用以下函数：

QLoggingCategory::setFilterRules(QStringLiteral("QHotkey.warning=false"));

这将关闭QHotkey的所有警告（目前它只使用警告，所以这就足够了）。有关日志类别的更多信息，请查看Qt文档。

线程安全

QHotkey类本身是可重入的 - 这意味着您可以在任何线程上创建所需数量的实例。这允许您在所有线程上使用QHotkey。但是您不应该在与实例所属线程不同的线程上使用QHotkey实例！在内部，系统使用一个单例实例来处理热键事件并将它们分发给QHotkey实例。这个内部类是完全线程安全的。

然而，这个单例实例只在主线程上运行。（原因之一是一些操作系统函数不是线程安全的）。为了实现线程热键，关键功能（注册/注销热键和按键转换）都在主线程上运行。其他线程上的QHotkey实例使用QMetaObject::invokeMethod和Qt::BlockingQueuedConnection。

对您来说，这意味着：主线程以外的QHotkey实例在注册/注销/转换热键时可能需要更长的时间，因为它们必须等待主线程为它们执行此操作。**重要：**然而，这个功能还有一个额外的限制：主线程以外的QHotkey实例必须在主事件循环结束之前注销或销毁。否则，您的应用程序在销毁热键时会挂起。这个限制不适用于主线程上的实例。此外，如果您在循环开始之前更改快捷键或注册/注销，直到它实际开始，也会发生同样的情况。

文档

文档可在发布版本和GitHub Pages上获取。

该文档使用doxygen创建。它包括HTML文档和Qt帮助文件，可以包含在QtCreator（QtAssistant）中以显示F1帮助（有关更多详细信息，请参阅添加外部文档）。

技术细节

要求

明确支持仅限最新的Qt LTS版本，但可能与早期版本兼容
至少需要QtGui模块（QGuiApplication）。不支持基于控制台应用程序的热键（由操作系统限制）。但您可以创建一个没有可见窗口的GUI应用程序。
C++11

已知限制

只能使用单个按键/修饰符组合。如果使用QKeySequence，只会使用序列中的第一个按键+修饰符。
Qt::Key不区分普通数字和小键盘数字。然而，大多数键盘需要这种区分。因此，除非使用原生快捷键，否则无法为小键盘注册快捷键。
不支持所有按键，但支持大多数常用按键。不同平台之间存在差异，并且取决于键盘布局。例如，"Delete"在Windows和Mac上可用，但在X11上不可用（至少在我的测试机器上）。我尽可能使用操作系统函数，但由于需要将Qt::Key值转换为原生按键，存在一些限制。如果需要这样的按键，请尝试使用原生快捷键。
注册的按键将被QHotkey"占用"。这意味着在您的应用程序消耗了热键后，它将不会发送给活动应用程序。这是由操作系统决定的，无法更改。
如果在X11上收到QHotkey: Failed to register hotkey. Error: BadAccess (attempt to access private resource denied)错误，这意味着您正在尝试注册一个对X11私有的热键。这些按键无法使用普通API注册。